---
title: "Send Contracts From Pipedrive Deals"
description: "Send a SignatureAPI contract when a Pipedrive deal is won. A Pipedrive automation calls an automation tool, which creates the envelope and updates the deal."
canonical: "https://signatureapi.com/docs/integrations/pipedrive"
source: "https://signatureapi.com/docs/integrations/pipedrive.md"
last_verified_api_version: "1.18.0"
---

# Send Contracts From Pipedrive Deals

Send a SignatureAPI contract when a Pipedrive deal is won. A Pipedrive automation calls an automation tool, which creates the envelope and updates the deal.

_Last verified against API version 1.18.0._

Pipedrive's automation webhook action can send a JSON body, but its documentation lists no custom headers, and SignatureAPI needs the `X-API-Key` header. So the automation sends the deal to an automation tool's webhook, and that tool makes the SignatureAPI request. No SignatureAPI app is needed.

## Before you start

- A SignatureAPI [test API key](https://signatureapi.com/docs/api/test-mode) (it starts with `key_test_`).
- The document you send, at a URL on a [supported host](https://signatureapi.com/docs/api/resources/documents/url#external-store), or [uploaded to SignatureAPI](https://signatureapi.com/docs/api/resources/uploads/create) first. The examples use a sample PDF.
- A Pipedrive plan with the webhook action in Automations. [Pipedrive](https://support.pipedrive.com/en/article/automations-webhook-requests) offers it on Growth and higher plans, and only global admin users can create automated webhooks.
- An automation tool with an inbound webhook and an HTTP step, such as [Make](https://signatureapi.com/docs/integrations/make), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) or [n8n](https://signatureapi.com/docs/integrations/n8n).

## Send the envelope

1. **Create an inbound webhook in the tool**

   In your automation tool, create a webhook trigger and copy its URL. For Make, that is a **Custom webhook** in the **Webhooks** app.

2. **Create an automated webhook in Pipedrive**

   In Pipedrive, go to **Tools and apps** > **Webhooks**, click **+ Webhooks**, and select **Automated webhook**. Enter a name and the tool's URL. Pipedrive requires the URL to end with `/`, `&`, `?` or `=`, so add a `?` to the end if it ends in anything else.

3. **Add the webhook action to an automation**

   Create an automation that starts when a deal is won, and add the webhook action. Choose your webhook and the `POST` method, then build the body with the **Raw** option as JSON. Use the field button to insert the deal id, the person's name and the person's email. Pipedrive replaces each field with the deal's data when it sends the request.

4. **Create the envelope in the tool**

   Add an HTTP step after the webhook trigger and send this request, mapping the name, email and deal id from the webhook payload. Store the key in the tool's own credential storage, not in the step text.

HTTP request step settings for the "Deal contract" request:

1. **Method**: POST
2. **URL**: `https://api.signatureapi.com/v1/envelopes`
3. **Header**: `X-API-Key: YOUR_API_KEY`

   Store the key in your tool's secret or credential storage when it has one.
4. **Header**: `Content-Type: application/json`
5. **Body (raw JSON)**:

   ```json
   {
     "title": "Service Agreement - Acme Corp",
     "message": "Please review and sign the service agreement for your order.",
     "metadata": {
       "source": "pipedrive",
       "deal_id": "1042"
     },
     "topics": [
       "no_code",
       "pipedrive"
     ],
     "documents": [
       {
         "key": "service_agreement",
         "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
         "format": "pdf",
         "fixed_positions": [
           {
             "place_key": "signer_signature",
             "page": 1,
             "top": 172,
             "left": 210
           }
         ],
         "places": [
           {
             "key": "signer_signature",
             "type": "signature",
             "recipient_key": "signer"
           }
         ]
       }
     ],
     "recipients": [
       {
         "type": "signer",
         "key": "signer",
         "name": "Jane Doe",
         "email": "jane.doe@example.com"
       }
     ]
   }
   ```

`data.envelope_metadata.deal_id` comes back in every webhook event for this envelope, and the `pipedrive` topic lets an endpoint receive only these envelopes. Open **Automations** > **History** in Pipedrive and select a run to see the exact body Pipedrive sent.

## Get the result back

The tool receives the result, because Pipedrive's automation action only sends requests. Build it as a second scenario or workflow, as in [Make](https://signatureapi.com/docs/integrations/make#get-the-result-back).

1. **Register the tool's URL in SignatureAPI**

   Create a second inbound webhook in the tool. In the Dashboard, add a [webhook endpoint](https://signatureapi.com/docs/api/guides/how-to/set-up-webhooks) in test mode with that URL, subscribe to [`deliverable.generated`](https://signatureapi.com/docs/api/resources/events/deliverable-events#deliverablegenerated), which fires when the signed PDF is ready, and add the `pipedrive` topic. The [`envelope.completed`](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopecompleted) event comes earlier, while the PDF may still be generating, so use it only to update a status.

2. **Read the envelope before you act**

   Anyone who knows a webhook URL can call it, so read the envelope with your key before you update the deal. Put the id from `data.envelope_id` in the URL:

   HTTP request step settings for the "Completed envelope" request:

   1. **Method**: GET
   2. **URL**: `https://api.signatureapi.com/v1/envelopes/eb4cf433-a8af-4161-b37b-7ef57d423e56`
   3. **Header**: `X-API-Key: YOUR_API_KEY`

      Store the key in your tool's secret or credential storage when it has one.

3. **Update the deal**

   Send a `PATCH` request to `https://companydomain.pipedrive.com/api/v2/deals/{id}` with your Pipedrive API token in the `x-api-token` header, using `metadata.deal_id` as the `id`. Put the status in a custom field under `custom_fields`, whose keys are 40-character hashes ([Update a deal, API v2](https://developers.pipedrive.com/docs/api/v1/Deals#updateDeal), [API v2 overview](https://pipedrive.readme.io/docs/pipedrive-api-v2), [authentication](https://pipedrive.readme.io/docs/core-api-concepts-authentication)).

When `deliverable.status` is `generated`, `deliverable.url` downloads the signed PDF. That link expires after an hour, so download the file in the same run. If your account uses [authenticated deliverable URLs](https://signatureapi.com/docs/api/resources/deliverables/object#url), send your API key with the download. The same event can arrive twice, so skip a deal that already shows as signed. See [Webhooks](https://signatureapi.com/docs/api/webhooks).

## Related

- [Create an envelope](https://signatureapi.com/docs/api/resources/envelopes/create): every field of the request body.
- [Organize with topics and metadata](https://signatureapi.com/docs/api/guides/how-to/organize-topics-metadata).
- [Make](https://signatureapi.com/docs/integrations/make), [Zapier](https://signatureapi.com/docs/integrations/zapier/http-recipe) and [n8n](https://signatureapi.com/docs/integrations/n8n).

### Example: Deal contract

Sent when a Pipedrive deal is won.

```http
POST /v1/envelopes HTTP/1.1
Host: api.signatureapi.com
X-API-Key: YOUR_API_KEY
Content-Type: application/json

{
  "title": "Service Agreement - Acme Corp",
  "message": "Please review and sign the service agreement for your order.",
  "metadata": {
    "source": "pipedrive",
    "deal_id": "1042"
  },
  "topics": [
    "no_code",
    "pipedrive"
  ],
  "documents": [
    {
      "key": "service_agreement",
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "place_key": "signer_signature",
          "page": 1,
          "top": 172,
          "left": 210
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer"
        }
      ]
    }
  ],
  "recipients": [
    {
      "type": "signer",
      "key": "signer",
      "name": "Jane Doe",
      "email": "jane.doe@example.com"
    }
  ]
}
```

Response 201 Created:

```json
{
  "id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
  "title": "Service Agreement - Acme Corp",
  "label": null,
  "message": "Please review and sign the service agreement for your order.",
  "status": "processing",
  "attestation": "none",
  "language": "en",
  "mode": "test",
  "routing": "sequential",
  "timezone": "UTC",
  "timestamp_format": "MM/DD/YYYY HH:mm:ss",
  "snapshot_url": null,
  "branding": {
    "logo": null,
    "accent_color": "#2463EB",
    "email": {
      "footer": null,
      "logo_position": "left",
      "from": "noreply@signatureapi.com"
    }
  },
  "deliverable": {
    "id": "del_6FF89lKNyTNamOJCJd1tLL",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "name": null,
    "status": "pending",
    "type": "standard",
    "url": null,
    "password": null,
    "created_at": "2026-11-02T14:03:11.000Z",
    "generated_at": null,
    "timezone": "UTC",
    "language": "en",
    "timestamp_format": "MM/DD/YYYY HH:mm:ss",
    "included_documents": [
      "service_agreement"
    ]
  },
  "metadata": {
    "source": "pipedrive",
    "deal_id": "1042"
  },
  "sender": {
    "name": "Acme Corp Legal",
    "email": "legal@acme.example",
    "organization": "Acme Corp"
  },
  "captures": {},
  "documents": [
    {
      "id": "doc_HVl3Nj7XzTzX7jN3lVH5vn",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "key": "service_agreement",
      "title": null,
      "page_count": 1,
      "url": "https://pub-9cb75390636c4a8a83a6f76da33d7f45.r2.dev/docs-samples/service-agreement.pdf",
      "format": "pdf",
      "fixed_positions": [
        {
          "page": 1,
          "top": 172,
          "left": 210,
          "place_key": "signer_signature"
        }
      ],
      "places": [
        {
          "key": "signer_signature",
          "type": "signature",
          "recipient_key": "signer",
          "height": 60
        }
      ]
    }
  ],
  "recipients": [
    {
      "id": "re_49r1R2jpPDz8hSpP75ZkPp",
      "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
      "type": "signer",
      "key": "signer",
      "email": "jane.doe@example.com",
      "name": "Jane Doe",
      "ceremony": {
        "authentication": [
          {
            "type": "email_link",
            "subject_override": null,
            "message_override": null
          }
        ],
        "embeddable_in": [],
        "redirect_url": null,
        "redirect_delay": 3,
        "url": null,
        "url_variant": "standard"
      },
      "ceremony_creation": "automatic",
      "delivery_type": "email",
      "signature_options": [
        "typed",
        "drawn"
      ],
      "status": "pending",
      "status_updated_at": "2026-11-02T14:03:11.000Z",
      "completed_at": null
    }
  ],
  "topics": [
    "no_code",
    "pipedrive"
  ],
  "created_at": "2026-11-02T14:03:11.000Z",
  "completed_at": null
}
```

Response 422 Unprocessable Content:

```json
{
  "type": "https://signatureapi.com/docs/v1/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "errors": [
    "recipients[0].email must be a valid email address."
  ]
}
```

Errors that any request can return (authentication, rate limits, server errors) are on the [Errors](https://signatureapi.com/docs/api/errors) and [Authentication](https://signatureapi.com/docs/api/authentication) pages.
