Webhooks

Send a test event

POST /v1/webhooks/{webhook_id}/test

Scope: webhooks:write
Tier: Tier 1
Data: Account data
Idempotency: Idempotency-Key: required

Queues one webhook.test event to this endpoint only. The body must be empty or {}.

Parameters

Name	In	Type	Required	Description
`webhook_id`	path	string (WebhookEndpointId)	yes
`Idempotency-Key`	header	string	yes	Your unique value for this logical operation (a UUID is fine). Scoped to your API client, kept 24 hours. (min length 1; max length 255)
`X-Correlation-ID`	header	string	no	Your own trace value, logged with the request. Metadata only, never identity. (min length 1; max length 128)

Request body

Empty, or {}.

JSON: EmptyRequest (optional)

Response

202: Queued.

Header	Meaning
`X-Request-ID`	The DialerBee request id. Quote it to support. Every response carries X-Request-ID: req_<ULID>, or edge_<32 hex> when the edge answered before the request reached the API.
`Cache-Control`	Always `no-store`.
`Idempotency-Replayed`	`true` when this answer is the stored answer of an earlier request with the same `Idempotency-Key`.

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/webhooks/wh_0f8fad5b-d9cb-469f-a165-70867728950e/test" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H 'Idempotency-Key: 5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a' \
  -H "Content-Type: application/json" \
  --data '{}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.webhooks.send_test(
    "wh_0f8fad5b-d9cb-469f-a165-70867728950e",
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

202

{
  "event_id": "evt_0f8fad5b-d9cb-469f-a165-70867728950e",
  "delivery_id": "whd_0f8fad5b-d9cb-469f-a165-70867728950e"
}

Error examples

403 webhooks_disabled

{
  "type": "https://docs.dialerbee.com/errors/webhooks-disabled",
  "title": "Webhooks not enabled",
  "status": 403,
  "detail": "Webhooks are not switched on for this account.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "webhooks_disabled",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

403 insufficient_scope

{
  "type": "https://docs.dialerbee.com/errors/insufficient-scope",
  "title": "Not permitted",
  "status": 403,
  "detail": "The API client does not hold the scope this operation requires.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "insufficient_scope",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

409 outcome_unknown

{
  "type": "https://docs.dialerbee.com/errors/outcome-unknown",
  "title": "Outcome unknown",
  "status": 409,
  "detail": "An earlier request with this Idempotency-Key may or may not have taken effect: the platform did not confirm it.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "outcome_unknown",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Status	Code	Title
401	`invalid_api_key`	Invalid API key
403	`api_access_disabled`	API access disabled
403	`ip_not_allowed`	IP address not allowed
403	`insufficient_scope`	Not permitted
400	`credential_in_url`	Credential in URL
400	`credential_in_body`	Credential in body
400, 422	`validation_failed`	Invalid request
413	`payload_too_large`	Payload too large
415	`unsupported_media_type`	Unsupported media type
400	`idempotency_key_required`	Idempotency-Key required
404	`not_found`	Not found
403	`webhooks_disabled`	Webhooks not enabled
409	`conflict`	Request in progress
409	`idempotency_conflict`	Idempotency key reused
409	`outcome_unknown`	Outcome unknown
429	`rate_limit_exceeded`	Too many requests
503	`temporarily_unavailable`	Temporarily unavailable
503	`upstream_unavailable`	Temporarily unavailable
502	`upstream_invalid_response`	Upstream error
500	`internal_error`	Internal error

Objects

EmptyRequest

An empty JSON object.

WebhookDeliveryQueued

Field	Type	Required	Description
`event_id`	string (WebhookEventId)	yes	A webhook event. Retries and replays keep the same event id. `evt_` + a lower-case UUID.
`delivery_id`	string (WebhookDeliveryId)	yes	One delivery of an event to one endpoint. A replay is a new delivery. `whd_` + a lower-case UUID.