Webhook API

The Webhook API receives events from Pipedrive when deal data changes.

POST /webhooks/pipedrive

Receives webhook events from Pipedrive. This is a receive-only endpoint -- it logs events to CloudWatch for monitoring and auditing purposes.

Pipedrive Webhook Configuration

Setting	Value
Webhook ID	1345147
Event action	*.deal (all deal events)
HTTP method	POST
Endpoint URL	https://jwfqmc0638.execute-api.us-east-1.amazonaws.com/webhooks/pipedrive

Request Body

Pipedrive sends a JSON payload with the following structure:

{
  "v": 1,
  "matches_filters": null,
  "meta": {
    "action": "updated",
    "object": "deal",
    "id": 123,
    "company_id": 12345678,
    "user_id": 98765,
    "host": "phd-advantage.pipedrive.com",
    "timestamp": 1709913600,
    "change_source": "app",
    "is_bulk_update": false
  },
  "current": {
    "id": 123,
    "title": "Jane Doe - Dissertation Editing",
    "stage_id": 1,
    "status": "open",
    "value": 2786.08,
    "currency": "USD"
  },
  "previous": {
    "stage_id": 0,
    "status": "open"
  },
  "event": "updated.deal"
}

Response

The endpoint always returns 200 OK to acknowledge receipt:

{
  "received": true
}

Returning a non-200 status would cause Pipedrive to retry the webhook, so the handler catches all errors internally and still returns 200.

Logged Events

All webhook payloads are logged to CloudWatch Logs for the webhookHandler function. Useful log data includes:

• meta.action: The event type (added, updated, deleted)
• meta.id: The Pipedrive deal ID
• current.stage_id: The new pipeline stage
• current.status: Deal status (open, won, lost, deleted)

Viewing Webhook Logs

AWS_SDK_LOAD_CONFIG=1 npx serverless logs \
  --function webhookHandler \
  --tail \
  --aws-profile dissertation-editor

Registering or Updating the Webhook

If the webhook needs to be re-registered (e.g., after a URL change), use the Pipedrive API:

curl -X POST "https://api.pipedrive.com/v1/webhooks?api_token=<TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscription_url": "https://jwfqmc0638.execute-api.us-east-1.amazonaws.com/webhooks/pipedrive",
    "event_action": "*",
    "event_object": "deal",
    "http_auth_user": "",
    "http_auth_password": ""
  }'

The API token is stored in SSM at /dissertation-editor/pipedrive/api-token.