Create a webhook subscription

POST https://api.dairo.app/v1/webhooks

Registers an active webhook and returns it together with a one-time signingSecret (prefixed whsec_, flagged secretShownOnce) that appears only in this response — store it immediately. url must be an HTTPS endpoint on port 443 with a public host (loopback, private, and link-local addresses are rejected) and at most 2048 characters, and events must list at least one subscribable event type — the synthetic webhook.ping is not one and is rejected. Each URL may be connected once per organization, so a create for a URL already registered returns 409. Dairo delivers each matching event as a JSON POST carrying X-Dairo-Event, X-Dairo-Event-Id, X-Dairo-Timestamp (unix seconds), and X-Dairo-Signature, where the signature is v2=<hex HMAC-SHA256> over <timestamp>.<event id>.<raw body> keyed by the hex SHA-256 of the secret; verify it and the timestamp before trusting the payload, as described in verifying webhooks. Pass an optional label to name the endpoint. The create is not deduplicated by key: a retry for a URL that was registered meanwhile returns 409, so list your webhooks to find it. Only a key whose creator is an organization owner or admin may manage webhooks, and a key restricted to specific inboxes is refused with a 403, because a webhook receives the events of every inbox. Rate limited to 10 creates per hour; requires the webhooks:write scope.

Scope: webhooks:write. Send the API key as a bearer token; Scopes lists what each one reaches.

Request

curl -X POST "https://api.dairo.app/v1/webhooks" \
  -H "Authorization: Bearer $DAIRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "events": [
      "message.received"
    ]
  }'

Headers

Body

Required, application/json: CreateWebhookRequest.

Response

201 Created. Body: application/json, CreateWebhookResponse.

{
  "object": "webhook",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://example.com",
  "events": [
    "message.received"
  ],
  "label": "production",
  "status": "active",
  "createdAt": "2026-10-19T09:30:00Z",
  "lastDeliveryAt": "2026-10-19T09:30:00Z",
  "secondarySecretExpiresAt": "2026-10-19T09:30:00Z",
  "secondarySecretActive": true,
  "consecutiveFailures": 0,
  "pausedReason": null,
  "autoPaused": true,
  "autoPausedAt": "2026-10-19T09:30:00Z",
  "signingSecret": "string",
  "secretShownOnce": true
}

Errors

Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.