/v1/webhooks

Register, update, rotate, and delete outbound webhook endpoints — the URLs we POST ask.completed deliveries to when you use async mode. These endpoints are session-authenticated via your dashboard login.

Looking for the wire format and signature verification? See the Webhooks concept page.

Legacy endpoint. This documents an older surface kept for back-compat with existing integrations. New integrations should use /v1/check instead — see the quickstart for the modern API.

Webhook object

Field	Type	Description
`id`optional	`string (uuid)`	Endpoint identifier.
`url`optional	`string`	Target URL (http or https).
`description`optional	`string \| null`	Optional label up to 200 chars.
`events`optional	`'ask.completed'[]`	Subscribed events. Currently only ask.completed is emitted.
`enabled`optional	`boolean`	Disabled endpoints receive no deliveries.
`created_at`optional	`string (ISO)`
`secret`optional	`string`	HMAC signing secret. Returned ONLY on POST (creation) and on PATCH with rotate_secret: true. Never returned from GET.

GET /v1/webhooks

GET/v1/webhooks— List all webhook endpoints for the calling account

json

{
  "request_id": "…",
  "webhooks": [
    {
      "id": "…",
      "url": "https://example.com/hooks/mentionsapi",
      "description": "Prod ingestion",
      "events": ["ask.completed"],
      "enabled": true,
      "created_at": "2026-04-10T11:04:00.000Z"
    }
  ]
}

POST /v1/webhooks

POST/v1/webhooks— Register a new endpoint. Returns the signing secret ONCE.

Field	Type	Description
`url` required	`string`	Must start with http:// or https://.
`description`optional	`string`	Up to 200 chars.
`events`optional	`'ask.completed'[]`	Default is ["ask.completed"].

json

// Response
{
  "request_id": "…",
  "webhook": {
    "id": "…",
    "url": "https://example.com/hooks/mentionsapi",
    "description": null,
    "events": ["ask.completed"],
    "enabled": true,
    "created_at": "2026-04-10T11:04:00.000Z",
    "secret": "9c1e…b3"   // 64-char hex, 32 bytes entropy. Store now — never returned again.
  }
}

PATCH /v1/webhooks/:id

PATCH/v1/webhooks/:id— Update url, description, events, enabled; or rotate the secret

Field	Type	Description
`url`optional	`string`
`description`optional	`string \| null`
`events`optional	`'ask.completed'[]`
`enabled`optional	`boolean`	Disable without deleting.
`rotate_secret`optional	`boolean`	When true, a new HMAC secret is generated and returned in the response. The old secret stops verifying immediately.

At least one field must be provided. An empty PATCH returns 400 invalid_request.

DELETE /v1/webhooks/:id

DELETE/v1/webhooks/:id— Permanently remove an endpoint

json

{ "request_id": "…", "deleted": true, "id": "…" }

Errors

Field	Type	Description
`invalid_request`optional	`400`	Body failed validation (bad URL, unknown event, empty PATCH).
`unauthorized`optional	`401`	No active dashboard session.
`not_found`optional	`404`	Webhook id does not belong to your account.