Create a webhook
Creates a new webhook endpoint for the authenticated customer. A webhook is version 2 unless the request sets webhook_version to 1: Svix delivers it, signed with the webhook-id, webhook-timestamp and webhook-signature headers, and retries it on its own schedule, so retry_count and timeout_seconds apply to version 1 only. sender_profile applies to version 1 only and is ignored on version 2; is_inheritable applies to version 2 only. A version 1 webhook's response returns its sender_profile selection, with an empty event_types when it is not cloned onto sender profiles; a version 2 webhook's response leaves sender_profile out.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/v3/webhooks" \ -H "Idempotency-Key: req_abc123_retry1" \ -H "Content-Type: application/json" \ -d '{ "display_name": "Order Notifications", "endpoint_url": "https://example.com/webhooks/orders", "event_types": [ "contact", "message", "templates" ], "event_filters": { "message": [ "delivered", "failed" ], "templates": [ "approved", "rejected" ] }, "retry_count": 3, "timeout_seconds": 30, "is_inheritable": false, "sandbox": false }'{
"success": true,
"data": {
"id": "d4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
"customer_id": "00000000-0000-0000-0000-000000000000",
"display_name": "Order Notifications",
"endpoint_url": "https://example.com/webhooks/orders",
"signing_secret": "whsec_a1b2c3d4e5f6g7h8i9j0",
"is_active": true,
"event_types": [
"contact",
"message",
"templates"
],
"event_filters": {
"message": [
"delivered",
"failed"
]
},
"sender_profile": null,
"retry_count": 3,
"timeout_seconds": 30,
"is_inheritable": false,
"webhook_version": 2,
"last_delivery_attempt_at": null,
"last_successful_delivery_at": null,
"consecutive_failures": 0,
"created_at": "2026-01-15T10:30:00+00:00",
"updated_at": null
},
"error": null,
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-11-05T15:14:26.4889409+00:00",
"version": "v3"
}
}{
"success": false,
"data": null,
"error": {
"code": "VALIDATION_001",
"message": "Endpoint URL must be a valid HTTP or HTTPS URL",
"details": null,
"doc_url": "https://docs.sent.dm/reference/api/error-catalog"
},
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-11-05T15:14:26.4892783+00:00",
"version": "v3"
}
}{
"success": false,
"data": null,
"error": {
"code": "INTERNAL_001",
"message": "An unexpected error occurred while creating the webhook",
"details": null,
"doc_url": "https://docs.sent.dm/reference/api/error-catalog"
},
"meta": {
"request_id": "req_7X9zKp2jDw",
"timestamp": "2026-11-05T15:14:26.4892791+00:00",
"version": "v3"
}
}