In your Pipedrive account, navigate to Settings > Integrations > Webhooks (or use the API: POST /v1/webhooks) to create a webhook subscription for the deals object with event_action set to updated
Specify your endpoint URL and optionally configure basic authentication credentials that Pipedrive will include in the Authorization header of each delivery
On your endpoint, parse the incoming JSON payload: the current field contains the deal's full state after the update, and the previous field contains the state before — diff the stage_id field across both to detect stage changes
Respond with HTTP 200 within your endpoint's processing window; offload heavy processing to a background job and acknowledge receipt immediately
Filter relevant stage changes in your handler by comparing current.stage_id to a list of target stage IDs rather than processing every deal update — Pipedrive delivers a webhook for all deal property changes, not just stage transitions
Use the meta.id field (the deal ID) and meta.timestamp to implement idempotency, as Pipedrive may redeliver webhooks on transient delivery failures
Known gotchas
Pipedrive webhooks deliver the full deal object on every update regardless of which field changed — there is no field-level filtering on the subscription, so your handler must implement its own change detection logic
If your endpoint returns non-2xx responses consistently, Pipedrive will deactivate the webhook after a period of failed deliveries without proactive notification to the account owner — monitor endpoint health actively
Pipedrive's webhook payload structure uses snake_case field names while the REST API responses for the same objects use camelCase in some older endpoints — validate your field name expectations against a live webhook delivery rather than API documentation
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp