Webhooks

Rotate an endpoint's signing secret, with a 24-hour overlap

POST /v1/webhooks/{webhook_id}/rotate-secret

Scope

webhooks:write

Tier

Tier 1

Data

Account data

Idempotency

Idempotency-Key: required

The new secret is shown once. For 24 hours every delivery carries both signatures (DialerBee-Signature: sha256=<new>,sha256=<old>), so you can switch your receiver without losing events. After previous_secret_expires_at only the new secret signs. secret is null only on a replayed answer (Idempotency-Replayed: true). DialerBee never stores the secret; if you lost it, rotate it. The body must be empty or {}.

Parameters

Request body

Empty, or {}.

JSON: EmptyRequest (optional)

Response

200: The new secret (shown once).

Examples

Request example

curl

curl -sS -X POST \
  "https://app.dialerbee.com/api/v1/webhooks/wh_0f8fad5b-d9cb-469f-a165-70867728950e/rotate-secret" \
  -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.rotate_secret(
    "wh_0f8fad5b-d9cb-469f-a165-70867728950e",
    idempotency_key="5f2b7c1e-8a3d-4c6f-9b0e-2d4a6c8e1f3a",
)

Response example

200

{
  "webhook_id": "wh_0f8fad5b-d9cb-469f-a165-70867728950e",
  "secret": "whsec_EXAMPLE-shown-once-keep-it-safe",
  "secret_hint": "safe",
  "previous_secret_expires_at": "2026-09-30T12:00:00Z"
}

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

Objects

EmptyRequest

An empty JSON object.

WebhookSecret