Skip to content
Docs

Webhook endpoints

Manage the endpoints that receive signed webhook events. All endpoints need an API key.

The signing secret is returned only when an endpoint is created or its secret is rotated. Store it then. URLs must use https and carry no credentials (invalid_url otherwise), and each host can have up to 3 endpoints (webhook_limit_reached). An endpoint that fails repeatedly is disabled; consecutiveFailures and disabledReason show why, and setting active: true re-enables it.

GET /webhooks

List webhook endpoints. Auth: API key.

Response 200

Body (array of objects)

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
urlstringyes-
events"booking.created" | "booking.rescheduled" | "booking.cancelled" | "session.created" | "session.updated" | "session.cancelled"[]yes-
activebooleanyes-
consecutiveFailuresintegeryes-9007199254740991–9007199254740991
disabledReasonstring | nullyes-
createdAtstring (date-time)yes-

Errors: unauthorized

curl -X GET "https://devalender.com/api/webhooks" \
  -H "Authorization: Bearer dvl_..."

POST /webhooks

Create an endpoint; the signing secret is shown once. Auth: API key.

Request body

FieldTypeRequiredDefault / limits
urlstringyes1–2000 chars
events"booking.created" | "booking.rescheduled" | "booking.cancelled" | "session.created" | "session.updated" | "session.cancelled"[]nomin 1 items

Response 201

Body

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
urlstringyes-
events"booking.created" | "booking.rescheduled" | "booking.cancelled" | "session.created" | "session.updated" | "session.cancelled"[]yes-
activebooleanyes-
consecutiveFailuresintegeryes-9007199254740991–9007199254740991
disabledReasonstring | nullyes-
createdAtstring (date-time)yes-
secretstringyes-

Errors: invalid_request, invalid_url, webhook_limit_reached, unauthorized

curl -X POST "https://devalender.com/api/webhooks" \
  -H "Authorization: Bearer dvl_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"string"}'

PATCH /webhooks/:id

Change the URL, events or active flag. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Request body

FieldTypeRequiredDefault / limits
urlstringno1–2000 chars
events"booking.created" | "booking.rescheduled" | "booking.cancelled" | "session.created" | "session.updated" | "session.cancelled"[]nomin 1 items
activebooleanno-

Response 200

Body

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
urlstringyes-
events"booking.created" | "booking.rescheduled" | "booking.cancelled" | "session.created" | "session.updated" | "session.cancelled"[]yes-
activebooleanyes-
consecutiveFailuresintegeryes-9007199254740991–9007199254740991
disabledReasonstring | nullyes-
createdAtstring (date-time)yes-

Errors: invalid_request, invalid_url, not_found, unauthorized

curl -X PATCH "https://devalender.com/api/webhooks/<id>" \
  -H "Authorization: Bearer dvl_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"string"}'

DELETE /webhooks/:id

Delete an endpoint. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Response 204

No body.

Errors: not_found, unauthorized

curl -X DELETE "https://devalender.com/api/webhooks/<id>" \
  -H "Authorization: Bearer dvl_..."

POST /webhooks/:id/rotate-secret

Issue a new signing secret. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Response 200

Body

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
urlstringyes-
events"booking.created" | "booking.rescheduled" | "booking.cancelled" | "session.created" | "session.updated" | "session.cancelled"[]yes-
activebooleanyes-
consecutiveFailuresintegeryes-9007199254740991–9007199254740991
disabledReasonstring | nullyes-
createdAtstring (date-time)yes-
secretstringyes-

Errors: not_found, unauthorized

curl -X POST "https://devalender.com/api/webhooks/<id>/rotate-secret" \
  -H "Authorization: Bearer dvl_..."

POST /webhooks/:id/test

Send a test event to the endpoint. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Response 200

Body

FieldTypeRequiredDefault / limits
okbooleanyes-
statusinteger | nullyes-
errorstring | nullyes-

Errors: not_found, unauthorized

curl -X POST "https://devalender.com/api/webhooks/<id>/test" \
  -H "Authorization: Bearer dvl_..."

GET /webhooks/:id/deliveries

Recent delivery attempts, newest first. Pass before=<createdAt>,<id> of the last item to get the next page. Auth: API key.

Path parameters

FieldTypeRequiredDefault / limits
idstringyes-

Query parameters

FieldTypeRequiredDefault / limits
limitintegernodefault 50; 1–200
beforestringno-

Response 200

Body (array of objects)

FieldTypeRequiredDefault / limits
idstring (uuid)yes-
eventIdstring (uuid)yes-
eventTypestringyes-
attemptsintegeryes-9007199254740991–9007199254740991
status"pending" | "delivered" | "failed"yes-
lastStatusinteger | nullyes-
lastErrorstring | nullyes-
nextAttemptAtstring (date-time) | nullyes-
deliveredAtstring (date-time) | nullyes-
createdAtstring (date-time)yes-

Errors: invalid_request, not_found, unauthorized

curl -X GET "https://devalender.com/api/webhooks/<id>/deliveries" \
  -H "Authorization: Bearer dvl_..."