Dairo Docs
GuidesAPI referenceDashboard
API referenceWebhooks

List webhook subscriptions

Returns every webhook subscription in your organization, newest first, as an unpaginated list envelope — data[] holds the webhooks and there is no pagination cursor.

Endpoint
GET https://api.dairo.app/v1/webhooks

Returns every webhook subscription in your organization, newest first, as an unpaginated list envelope — data[] holds the webhooks and there is no pagination cursor. Each entry carries id, url, the subscribed events, label, status (active or paused), createdAt, and lastDeliveryAt (null until the first successful delivery). Delivery-health fields are also surfaced: consecutiveFailures, autoPaused, and pausedReason — the last is auto:delivery_failures when Dairo disabled an endpoint after repeated failures. Signing secrets are never returned here; the raw secret is shown only once, in the create response. Requires the webhooks:read scope.

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

Request

cURL
curl "https://api.dairo.app/v1/webhooks" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

Response

200 Success. Body: application/json, WebhookListResponse.

FieldTypeRequiredDescription
object"list"yes
dataarray of Webhookyes
paginationPaginationyes
200
{
  "object": "list",
  "data": [
    {
      "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"
    }
  ],
  "pagination": {
    "nextCursor": "string",
    "hasMore": true
  }
}

Errors

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

StatusMeaning
400The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch).
401The API key is missing or invalid.
403The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted).
404No such resource in this account (resource_not_found).
422The request is well-formed but a field failed validation (validation_failed).
429Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached).
500An unexpected error; retry with backoff, then contact support (internal_error).

Get one thread with its messages

Fetches one thread by threadId (a UUID) together with its messages, oldest first.

Create a webhook subscription

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.

On this page

RequestResponseErrors