Webhooks API

10 operations · all resources

What this covers#

Signed, retried event delivery per project. The signing secret is returned once at creation; deliveries that exhaust their retries are readable as dead letters.

Every example below runs as written once these are exported:

export DVAARIK_API_KEY="dvk_..."        # project API key, server side only
export DVAARIK_TOKEN="<account access token>"   # console session, from POST /console/auth/login
export ENDPOINT_ID="<uuid>"
export PROJECT_ID="<uuid>"

A <value> inside a JSON body is a value you supply. Responses are JSON; every error body is { "detail": … }. Each schema is expanded once per page, where it first appears.

Machine door errors#

Raised by the project-key dependency before any handler on this page runs.

Scopes used on this page: webhook:read, webhook:write. Mint a key with only these.

Account door errors#

Operations — project API key#

Call these from your own server with a project key. Never from a browser or a mobile bundle.

GET /v2/projects/{project_id}/webhooks#

List the project's endpoints. include_disabled=true also returns disabled ones.

WebhookEndpointInfo#

Plus the machine-door errors above. Full list on the errors page.

curl -sS -X GET "https://api.developers.dvaarik.com/v2/projects/$PROJECT_ID/webhooks" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

POST /v2/projects/{project_id}/webhooks#

Register a public HTTPS endpoint. The 201 carries the signing secret once; no route returns it again.

Request body: CreateWebhookEndpointRequest.

CreateWebhookEndpointRequest#

CreatedWebhookEndpoint#

The 201, and the ONLY response that ever contains the secret.

Plus the machine-door errors above. Full list on the errors page.

curl -sS -X POST "https://api.developers.dvaarik.com/v2/projects/$PROJECT_ID/webhooks" \
  -H "X-Api-Key: $DVAARIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "primary",
    "url": "https://example.com/hooks/dvaarik",
    "event_types": [
      "call.completed",
      "call.failed"
    ]
  }'

DELETE /v2/projects/{project_id}/webhooks/{endpoint_id}#

Disable the endpoint, bump its revision and cancel queued deliveries.

Plus the machine-door errors above. Full list on the errors page.

curl -sS -X DELETE "https://api.developers.dvaarik.com/v2/projects/$PROJECT_ID/webhooks/$ENDPOINT_ID" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

POST /v2/projects/{project_id}/webhooks/{endpoint_id}/test#

Queue a signed webhook.ping. The 202 means the delivery was recorded, not that it arrived.

WebhookTestResult#

What a test ping queued, not what a receiver said. queued is False when an identical ping is already waiting: the dedupe key is the endpoint plus its revision plus the minute, so leaning on the button does not turn into a burst against the developer's own server. The delivery id is returned either way so the caller can find it in the dead letters.

Plus the machine-door errors above. Full list on the errors page.

curl -sS -X POST "https://api.developers.dvaarik.com/v2/projects/$PROJECT_ID/webhooks/$ENDPOINT_ID/test" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

GET /v2/projects/{project_id}/webhooks/dead-letters#

List deliveries that exhausted their retries, with attempt counts and the last error.

DeadLetterInfo#

Plus the machine-door errors above. Full list on the errors page.

curl -sS -X GET "https://api.developers.dvaarik.com/v2/projects/$PROJECT_ID/webhooks/dead-letters?limit=20" \
  -H "X-Api-Key: $DVAARIK_API_KEY"

Operations — account session#

The same resource through the console door. These are what the web console calls; both doors return the same shapes.

GET /console/v2/projects/{project_id}/webhooks#

List the project's endpoints. include_disabled=true also returns disabled ones.

Plus the account-door errors above. Full list on the errors page.

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/webhooks" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

POST /console/v2/projects/{project_id}/webhooks#

Register a public HTTPS endpoint. The 201 carries the signing secret once; no route returns it again.

Request body: CreateWebhookEndpointRequest.

Plus the account-door errors above. Full list on the errors page.

curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/webhooks" \
  -H "Authorization: Bearer $DVAARIK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "primary",
    "url": "https://example.com/hooks/dvaarik",
    "event_types": [
      "call.completed",
      "call.failed"
    ]
  }'

DELETE /console/v2/projects/{project_id}/webhooks/{endpoint_id}#

Disable the endpoint, bump its revision and cancel queued deliveries.

Plus the account-door errors above. Full list on the errors page.

curl -sS -X DELETE "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/webhooks/$ENDPOINT_ID" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

POST /console/v2/projects/{project_id}/webhooks/{endpoint_id}/test#

Queue a signed webhook.ping. The 202 means the delivery was recorded, not that it arrived.

Plus the account-door errors above. Full list on the errors page.

curl -sS -X POST "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/webhooks/$ENDPOINT_ID/test" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"

GET /console/v2/projects/{project_id}/webhooks/dead-letters#

List deliveries that exhausted their retries, with attempt counts and the last error.

Plus the account-door errors above. Full list on the errors page.

curl -sS -X GET "https://api.developers.dvaarik.com/console/v2/projects/$PROJECT_ID/webhooks/dead-letters?limit=20" \
  -H "Authorization: Bearer $DVAARIK_TOKEN"