Webhooks

Create a webhook endpoint

POST /v1/webhooks

Scope

webhooks:write

Tier

Tier 1

Data

Account data

Idempotency

Idempotency-Key: required

Limit

Up to 10 endpoints per account

The URL must be https:// and resolve to a public address. The answer is the only time the signing secret is shown: store it. secret is null only on a replayed answer (Idempotency-Replayed: true). DialerBee never stores the secret; if you lost it, rotate it. At most 10 endpoints per account.

Parameters

Request body

The endpoint.

JSON: WebhookEndpointCreateRequest

Response

201: The endpoint and its signing secret (shown once).

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/webhooks" \
  -H "Authorization: Bearer $DIALERBEE_API_KEY" \
  -H 'Idempotency-Key: 5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a' \
  -H "Content-Type: application/json" \
  --data '{
  "url": "https://crm.example.com/dialerbee/webhooks",
  "events": [
    "call.completed",
    "disposition.logged"
  ],
  "description": "CRM sync"
}'

Python (SDK)

from dialerbee import DialerBee

db = DialerBee()  # reads DIALERBEE_API_KEY from the environment

result = db.webhooks.create(
    url="https://crm.example.com/dialerbee/webhooks",
    events=["call.completed", "disposition.logged"],
    description="CRM sync",
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

201

{
  "id": "wh_0f8fad5b-d9cb-469f-a165-70867728950e",
  "url_preview": "https://crm.example.com/dialerbee/...",
  "host": "crm.example.com",
  "description": "CRM sync",
  "events": [
    "call.completed"
  ],
  "enabled": true,
  "secret_hint": "safe",
  "created_at": "2026-09-29T09:15:00Z",
  "updated_at": "2026-09-29T09:20:00Z",
  "secret": "whsec_EXAMPLE-shown-once-keep-it-safe"
}

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"
}

409 webhook_limit_reached

{
  "type": "https://docs.dialerbee.com/errors/webhook-limit-reached",
  "title": "Webhook endpoint limit reached",
  "status": 409,
  "detail": "The account already has the maximum number of webhook endpoints (10).",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "webhook_limit_reached",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

422 webhook_url_refused

{
  "type": "https://docs.dialerbee.com/errors/webhook-url-refused",
  "title": "Webhook URL refused",
  "status": 422,
  "detail": "The webhook URL must be https://, must resolve to a public address, and must not point to a private, loopback, link-local or cloud-metadata address.",
  "instance": "urn:dialerbee:request:req_01K6BZ3M9X4T7Q2V8N5R6P1W0C",
  "code": "webhook_url_refused",
  "request_id": "req_01K6BZ3M9X4T7Q2V8N5R6P1W0C"
}

Errors

Objects

WebhookEndpointCreateRequest

WebhookEndpointCreated