Webhooks

Webhooks notify your application when events happen in Driftwood — contacts created, companies updated, activities logged, etc. Configure an HTTPS endpoint and select which events to subscribe to.

The Webhook Endpoint Object

Field	Type	Description
`id`	uuid	Unique identifier
`account_id`	uuid	Account this webhook belongs to
`created_by`	uuid	User who created it
`url`	string	Your HTTPS endpoint URL
`description`	string	Description
`secret_prefix`	string	First characters of the signing secret
`events`	string[]	Events this webhook is subscribed to
`is_active`	boolean	Whether the webhook is enabled
`created_at`	datetime	Creation timestamp
`updated_at`	datetime	Last update timestamp

Available Events

Event	Description
`contact.created`	A contact was created
`contact.updated`	A contact was updated
`contact.deleted`	A contact was deleted
`company.created`	A company was created
`company.updated`	A company was updated
`company.deleted`	A company was deleted
`activity.created`	An activity was created
`activity.updated`	An activity was updated
`activity.deleted`	An activity was deleted
`project.created`	A project was created
`project.updated`	A project was updated
`project.deleted`	A project was deleted

Webhook Payload

When an event occurs, Driftwood sends a POST request to your URL with:

{
  "event": "contact.created",
  "timestamp": "2025-06-15T14:30:00Z",
  "data": {
    "id": "550e8400-...",
    "first_name": "Jane",
    "last_name": "Smith",
    ...
  }
}

Signature Verification

Each webhook delivery includes a signature header for verification. Use your signing secret (returned at creation time) to validate that the payload came from Driftwood.

Create Webhook

Endpoint: webhooks-create

Field	Type	Required	Description
`url`	string	Yes	Your HTTPS endpoint URL
`description`	string	No	Description
`events`	string[]	Yes	Events to subscribe to

curl -X POST https://api.driftwoodapp.com/api/webhooks-create \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/driftwood",
    "description": "Sync contacts to our data warehouse",
    "events": ["contact.created", "contact.updated", "contact.deleted"]
  }'

Response:

{
  "ok": true,
  "result": {
    "endpoint": {
      "id": "880e8400-...",
      "url": "https://your-app.com/webhooks/driftwood",
      "events": ["contact.created", "contact.updated", "contact.deleted"],
      "is_active": true
    },
    "signing_secret": "whsec_abc123..."
  }
}

List Webhooks

Endpoint: webhooks-list

curl -X POST https://api.driftwoodapp.com/api/webhooks-list \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Get Webhook

Endpoint: webhooks-get

Field	Type	Required	Description
`id`	uuid	Yes	Webhook endpoint ID

Update Webhook

Endpoint: webhooks-update

Field	Type	Required	Description
`id`	uuid	Yes	Webhook endpoint ID
`url`	string	No	New URL
`description`	string	No	New description
`events`	string[]	No	New event subscriptions
`is_active`	boolean	No	Enable or disable

Delete Webhook

Endpoint: webhooks-delete

Field	Type	Required	Description
`id`	uuid	Yes	Webhook endpoint ID

View Deliveries

See recent delivery attempts and their status.

Endpoint: webhooks-deliveries

Field	Type	Required	Description
`endpoint_id`	uuid	Yes	Webhook endpoint ID
`limit`	integer	No	Number of deliveries to return

Response:

{
  "ok": true,
  "result": {
    "deliveries": [
      {
        "id": "990e8400-...",
        "event_type": "contact.created",
        "status": "delivered",
        "http_status_code": 200,
        "attempt_count": 1,
        "completed_at": "2025-06-15T14:30:01Z",
        "created_at": "2025-06-15T14:30:00Z"
      }
    ]
  }
}

Delivery Status Values

Status	Description
`pending`	Not yet delivered
`delivered`	Successfully delivered (2xx response)
`failed`	All delivery attempts failed

Error Codes

Code	Description
`webhooks.invalid_request`	Malformed request body
`webhooks.invalid_id`	Invalid UUID format
`webhooks.not_found`	Webhook does not exist
`webhooks.url_required`	URL is required
`webhooks.invalid_url`	URL must be a valid HTTPS URL
`webhooks.internal`	Server error