Webhook Endpoints API

Create and manage webhook endpoints to receive event notifications

Manage webhook endpoints that receive event notifications from all do.dev services.

Create Endpoint

POST/v1/webhooks

Create a new webhook endpoint

Requires:platform:webhooks:manage

Body Parameters

urlstringrequired

The HTTPS URL that will receive webhook events

enabled_eventsstring[]required

Event types to subscribe to. Use ["*"] for all events, or specific types like ["send.email.*", "telco.lookup.completed"]

descriptionstring

Optional description for this endpoint

Create a webhook endpoint

curl -X POST https://api.do.dev/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://example.com/webhooks/dodev",
  "enabled_events": ["send.email.*", "telco.lookup.completed"],
  "description": "Production webhook handler"
}'

Response201

{
"id": "whep_abc123",
"url": "https://example.com/webhooks/dodev",
"enabled_events": ["send.email.*", "telco.lookup.completed"],
"description": "Production webhook handler",
"signing_secret": "whsec_EXAMPLE_SECRET_DO_NOT_USE",
"is_active": true,
"message": "Webhook endpoint created. Save the signing_secret - it will not be shown again."
}

The signing_secret is only returned at creation time. Store it securely — you'll need it to verify webhook signatures.

Event Filter Patterns

The enabled_events field supports wildcard patterns:

Pattern	Matches
`*`	All events from all services
`send.*`	All send events (`send.email.sent`, `send.email.delivered`, etc.)
`send.email.*`	All send email events
`telco.lookup.completed`	Only this specific event type

You can combine multiple patterns:

{
  "enabled_events": [
    "send.email.bounced",
    "send.email.complained",
    "telco.*"
  ]
}

List Endpoints

GET/v1/webhooks

List all webhook endpoints for your organization

Requires:platform:webhooks:read

List webhook endpoints

curl https://api.do.dev/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY"

Response200

{
"endpoints": [
  {
    "id": "whep_abc123",
    "url": "https://example.com/webhooks/dodev",
    "description": "Production webhook handler",
    "enabled_events": ["send.email.*", "telco.lookup.completed"],
    "is_active": true,
    "is_paused": false,
    "consecutive_failures": 0,
    "last_delivery_at": 1700000000000,
    "last_delivery_status": 200,
    "created_at": 1699900000000
  }
]
}

Get Endpoint

GET/v1/webhooks/{id}

Get a single webhook endpoint

Requires:platform:webhooks:read

Path Parameters

idstringrequired

The webhook endpoint ID

Test Endpoint

POST/v1/webhooks/{id}/test

Send a test event to a webhook endpoint

Requires:platform:webhooks:manage

Sends a synthetic platform.test event to the specified endpoint. Use this to verify your webhook handler is working correctly.

Send a test webhook

curl -X POST https://api.do.dev/v1/webhooks/whep_abc123/test \
-H "Authorization: Bearer YOUR_API_KEY"

Response200

{
"success": true,
"eventId": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"message": "Test event published. The webhook will be delivered shortly."
}

The test event payload looks like:

{
  "eventId": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "platform.test",
  "service": "platform",
  "data": {
    "message": "This is a test webhook event from do.dev",
    "endpoint_id": "whep_abc123"
  },
  "livemode": false,
  "createdAt": 1700000000000
}

Endpoint States

State	Description
Active	Endpoint is receiving events normally
Disabled	Manually disabled — no events delivered
Paused	Auto-paused after 10 consecutive delivery failures. Must be manually unpaused from the dashboard

Error Responses

{
"error": "url is required"
}

{
"error": "Webhook URL must use HTTPS"
}

{
"error": "unauthorized",
"message": "Invalid or missing API key"
}

{
"error": "forbidden",
"message": "Insufficient scope. Required: platform:webhooks:manage"
}