If you live in Pipedrive and you want Docusign Workflow Builder to fire the moment a deal moves to Contract sent (or any other event), webhooks are the right primitive. Pipedrive emits structured JSON on entity changes, Baton catches that JSON, and Workflow Builder starts a real agreement run. No polling, no Zapier middle-step, no glue Lambda to babysit.

This tutorial walks through the wiring end-to-end: the Pipedrive event you pick, the payload you get, the Baton inbound URL, and the failure modes you should plan for before you go to production.

The architecture in one diagram #

Pipedrive deal event
   │  POST (JSON, ~10s timeout)
   ▼
Baton inbound webhook
   │  - HTTP Basic Auth check
   │  - payload field -> workflow parameter mapping
   │  - idempotency on meta.correlation_id
   ▼
Docusign Workflow Builder (API trigger)
   │  - starts the workflow run
   ▼
Workflow does its thing: envelope, routing, conditional steps

Notice what's not there: no Pipedrive OAuth, no API key for Pipedrive stored anywhere, no polling job. Baton only accepts webhooks - it never calls back into Pipedrive. That's intentional and worth understanding before you design around it.

Step 1 - Build the Workflow Builder workflow with an API start trigger #

In Docusign, create a Workflow Builder workflow with the start method set to From an API call (Docusign's own walkthrough covers this for Power Automate; the pattern is identical for any external caller, including Baton).

Declare the workflow input parameters you'll need from Pipedrive. For a typical sales-contract use case, that's something like:

signer_email           (string)
signer_name            (string)
deal_title             (string)
deal_value             (number)
deal_currency          (string)
company_name           (string)
pipedrive_deal_id      (string)

Name these parameters exactly the way you plan to name the Pipedrive payload fields you'll route in. Baton matches payload keys to parameter names automatically - there's no JSONPath layer to twist things into shape, so the names need to line up.

Publish the workflow and grab the workflow ID. You'll plug it into Baton in Step 3.

Step 2 - Pick the right Pipedrive event #

Pipedrive has two flavours of webhook, and they're not equivalent.

Entity webhooks fire on every change to a chosen object. The event is the combination of an event_action and an event_object: create.deal, change.deal, delete.person, or wildcards like *.deal. This is documented in the Pipedrive Webhooks v2 guide. They're high volume and unfiltered - if you subscribe to change.deal, you'll get a payload every time anyone touches any deal.

Automation webhook requests are configured inside a Pipedrive workflow automation as an action step. You set the trigger and filters in the automation (e.g. Deal stage changes to 'Contract sent' AND deal value > 10,000), and only then does the webhook fire. The Pipedrive support docs cover the setup.

For agreement automation you almost always want the Automation flavour. You don't want Docusign firing every time someone edits the deal's notes - you want it firing on one specific business event.

Step 3 - Create the Baton inbound webhook #

In Baton's Command Center:

  1. Add a new inbound webhook, source platform Pipedrive.
  2. Bind it to the Workflow Builder workflow you published in Step 1 (Baton lists your published workflows after you connect your Docusign account).
  3. Set HTTP Basic Auth credentials. Pick a username/password pair you can paste into Pipedrive on the other side. This is the only authentication Pipedrive supports on outbound webhooks.
  4. Copy the inbound URL. It'll look like https://relay.iambaton.com/in/<your-tenant>/<integration-id>.

That's the whole Baton setup. There's no field-mapping screen because there's no field mapping - Baton matches payload field names directly to your workflow parameter names. If you named your Workflow Builder parameter signer_email, Baton looks for signer_email in the inbound payload.

Step 4 - Configure the Pipedrive webhook #

In Pipedrive: Settings → Tools and apps → Tools → Webhooks → +Webhook.

If you're using an entity webhook:

If you're using an Automation webhook request, the action lives inside the automation. The endpoint URL and Basic Auth fields are configured on the action step itself, then the automation's own trigger and filters decide when it fires.

Save it and fire a test event (drag a test deal to the trigger stage, then drag it back). You should see the webhook hit Baton within a second or two and the Workflow Builder run start.

Anatomy of a Pipedrive v2 webhook payload #

This is what lands at the Baton URL when a deal changes. Trimmed for readability:

{
  "meta": {
    "action": "change",
    "entity": "deal",
    "entity_id": "1234",
    "company_id": "99999",
    "correlation_id": "5f3a...",
    "id": "a1b2...",
    "is_bulk_edit": false,
    "timestamp": "2026-05-15T10:00:00.000Z",
    "attempt": 1
  },
  "data": {
    "id": 1234,
    "title": "Acme Corp - Annual License",
    "value": 48000,
    "currency": "USD",
    "stage_id": 7,
    "status": "open",
    "person_id": { "value": 88, "name": "Jane Doe", "email": [{"value": "jane@acme.com"}] },
    "org_id":    { "value": 42, "name": "Acme Corp" },
    "custom_fields": {
      "signer_email": "jane@acme.com",
      "signer_name":  "Jane Doe"
    }
  },
  "previous": { "...prior values for change events...": null }
}

The meta.correlation_id is the single most useful field to know about. Pipedrive sends the same correlation_id on retries of the same delivery, which is exactly the hook Baton uses to deduplicate. If your Workflow Builder run is idempotent on the deal ID anyway, that's two layers of safety.

Pipedrive's retry policy (and how it interacts with the relay) #

This is the part people get burned on. From the v2 webhook guide:

Two things follow from that:

  1. Your endpoint has to respond in under 10 seconds. Workflow Builder's API can be slow on cold paths. The reason Baton acks first and then starts the workflow asynchronously is exactly this - if Baton waited for Docusign to return before responding to Pipedrive, you'd hit the 10s ceiling on the first slow run and watch the ban counter tick.
  2. The retry counter on the ban side only increases on first-attempt failures. Failed retries don't accelerate the ban. So a slow deploy that drops a few first attempts is more dangerous than a 5xx storm during retries.

If you're rolling your own relay instead of using Baton, the failure mode to design around is: a deploy that takes the endpoint down for 90 seconds will burn the original attempt and the 3s retry, and that counts as one ban-counter increment. Ten of those across a day and your webhook is muted for 30 minutes - silently, from Pipedrive's side.

Handling stage changes idiomatically #

The most common Pipedrive → Docusign trigger is deal moved into stage X. The cleanest way to detect this in an entity webhook is:

meta.action      === "change"
meta.entity      === "deal"
data.stage_id    === <your contract-sent stage id>
previous.stage_id !== <your contract-sent stage id>

That last line is what stops you from re-firing on every subsequent edit of an already-moved deal. Baton applies the comparison server-side; if you're building from scratch, don't skip it.

For the Automation-webhook path you don't need this check - the Pipedrive automation only fires on the stage transition itself, not on subsequent edits.

Troubleshooting checklist #

When the relay doesn't fire, walk these in order:

  1. Pipedrive's webhook dashboard. Settings → Webhooks → click the row. It shows the last attempt's status code. A 401 here means your Basic Auth doesn't match what Baton expects; a 5xx is on the relay; nothing showing means the event filter didn't match.
  2. Baton's Action log. Each inbound delivery is recorded with its correlation_id, the matched workflow, and whether the Workflow Builder API call succeeded. Re-read why Docusign webhooks fail silently if the workflow itself starts but never produces an envelope - that's a different failure domain and Baton's action log won't catch it.
  3. Workflow Builder's run history. If Baton's log shows a successful start but no run, the workflow's API trigger may have rejected your inputs (missing required parameter, type mismatch).
  4. Pipedrive's ban list. A webhook that's been quiet for 30 minutes after a burst of failures is probably banned, not broken.

When to reach for fluidlabs instead #

If you're earlier in the design - still deciding whether agreement automation belongs in Workflow Builder vs Docusign CLM, or what the IAM surface gives you beyond the eSignature API - that's a strategy conversation and fluidlabs is the better entry point. Baton picks up once you've decided Workflow Builder is the right primitive and you need the relay to be production-grade.

Already settled on the architecture? The HubSpot tutorial and Salesforce tutorial cover the same pattern on the two source platforms that are live in Baton today - useful even if Pipedrive is what you're wiring, because the Workflow Builder side is identical.