Webhook Endpoints
Create, update, and manage webhook endpoint subscriptions.
Manage the webhook endpoints that receive event notifications. For an overview of how webhooks work, see the Webhooks guide.
List Webhook Endpoints
GET /api/v1/webhooksRequired scope: webhooks:read
Example Request
curl -X GET "https://app.erzycall.com/api/v1/webhooks" \
-H "X-API-Key: ek_live_abc123"Example Response
{
"data": [
{
"id": "wh_001",
"url": "https://your-app.com/webhook",
"events": ["call.ended", "contact.created"],
"isActive": true,
"description": "Production webhook",
"createdAt": "2025-01-10T08:00:00Z"
}
]
}Create Webhook Endpoint
Register a new webhook endpoint to receive event notifications.
POST /api/v1/webhooksRequired scope: webhooks:write
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | HTTPS URL to receive webhook deliveries |
events | string[] | Yes | Events to subscribe to (1–10). See available events |
description | string | No | Description (max 500 chars) |
Example Request
curl -X POST "https://app.erzycall.com/api/v1/webhooks" \
-H "X-API-Key: ek_live_abc123" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: create-webhook-prod" \
-d '{
"url": "https://your-app.com/webhook",
"events": ["call.ended", "call.failed", "contact.created"],
"description": "Production webhook"
}'Example Response (201 Created)
{
"data": {
"id": "wh_001",
"url": "https://your-app.com/webhook",
"events": ["call.ended", "call.failed", "contact.created"],
"secret": "whsec_abc123...",
"isActive": true,
"description": "Production webhook",
"createdAt": "2025-01-15T10:30:00Z"
}
}The secret is only returned on creation. Save it immediately for signature verification.
Errors
| Status | Code | Description |
|---|---|---|
| 422 | MAX_ENDPOINTS | Maximum 5 webhook endpoints per organization |
Update Webhook Endpoint
Update the URL, events, description, or active status of a webhook endpoint.
PATCH /api/v1/webhooks/{id}Required scope: webhooks:write
Request Body
All fields are optional. Only provided fields are updated.
| Field | Type | Description |
|---|---|---|
url | string | HTTPS URL |
events | string[] | Replace subscribed events (1–10) |
description | string | Description (max 500 chars) |
isActive | boolean | Enable or disable the endpoint |
Example Request
curl -X PATCH "https://app.erzycall.com/api/v1/webhooks/wh_001" \
-H "X-API-Key: ek_live_abc123" \
-H "Content-Type: application/json" \
-d '{"events": ["call.ended", "call.failed"], "isActive": true}'Example Response
{
"data": {
"id": "wh_001",
"url": "https://your-app.com/webhook",
"events": ["call.ended", "call.failed"],
"isActive": true,
"description": "Production webhook",
"createdAt": "2025-01-10T08:00:00Z"
}
}Delete Webhook Endpoint
Permanently delete a webhook endpoint. Pending deliveries will be cancelled.
DELETE /api/v1/webhooks/{id}Required scope: webhooks:write
Example Request
curl -X DELETE "https://app.erzycall.com/api/v1/webhooks/wh_001" \
-H "X-API-Key: ek_live_abc123"Response
Returns 204 No Content on success.
Rotate Signing Secret
Generate a new signing secret for an endpoint. The old secret is immediately invalidated.
POST /api/v1/webhooks/{id}/rotate-secretRequired scope: webhooks:write
Example Request
curl -X POST "https://app.erzycall.com/api/v1/webhooks/wh_001/rotate-secret" \
-H "X-API-Key: ek_live_abc123"Example Response
{
"data": {
"secret": "whsec_new_secret..."
}
}Update your webhook handler's signature verification code with the new secret immediately.