Webhook subscriptions

GET /webhooks

List webhook endpoints

The destinations this workspace sends events to, with the event types each one subscribes to. Create and edit them in Settings > Developers, or subscribe from code with POST /webhooks. A key limited to some agents lists the endpoints pinned to those agents only (the ones it may also remove), never one that takes every agent's events. The scope is webhooks:read (a key with webhooks:write has it too).

Scope: webhooks:read

Parameters

• limit optional in the query · integer

  Rows per page, 1 to 100.

• cursor optional in the query · string

  The next_cursor of the previous page.

Returns WebhookEndpoint

• id required string

  Id

• url required string

  Url

• events required string[]

  Events

• agent_id optional string

  The one agent it listens to; null for all.

• enabled required boolean

  Enabled

• disabled_reason optional string

  Why it is off: failures (deliveries kept failing), owner (switched off in the dashboard), maker_left (paused when the teammate who made it left the workspace). null while it is on.

• created_at optional string

  Created At

• description optional string

  A label for people, such as the app that subscribed.

Responses

• 200 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl https://www.bidii.ai/api/v2/webhooks \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"

POST /webhooks

Subscribe a webhook

A REST hook: events of the types you name are POSTed to url, signed with the secret this call answers (once; keep it). The same contract as an endpoint made in Settings > Developers: X-Bidi-Signature: t=<unix>,v1=<hex> over <t>.<raw body>, retries over 14 hours, and the delivery log there. Up to 10 endpoints per workspace (409 too_many_endpoints). A refused URL is 422 with the reason in details (url_not_https, url_private, url_unresolved, ...). Send Idempotency-Key so a retried subscribe makes one endpoint; the replay answers the endpoint with secret: null (the secret is never stored in the clear, so it is shown once only: rotate it in Settings > Developers if the first answer was lost). Each event type needs the key to hold the scope that reads its data (lead.* and form.submitted leads:read, ticket.* tickets:read, conversation.* and message.created conversations:read, contact.created and campaign.sent contacts:read, usage.threshold usage:read, the rest agents:read); 403 insufficient_scope otherwise. This is what the Zapier and Make apps call when a Zap or scenario is switched on.

Scope: webhooks:write

Request body

• url required string

  Where events are POSTed: https, a public host, port 443 or 8443.

• events required string[]

  The event types to send, by their D-3 names (lead.created, ticket.created, form.submitted, ...).

• agent_id optional string

  Only this agent's events; omit for every agent. A key limited to some agents must name one of them.

• description optional string

  A label for people, such as "Zapier: New lead". Settings > Developers shows it.

Returns WebhookEndpoint

• id required string

  Id

• url required string

  Url

• events required string[]

  Events

• agent_id optional string

  The one agent it listens to; null for all.

• enabled required boolean

  Enabled

• disabled_reason optional string

  Why it is off: failures (deliveries kept failing), owner (switched off in the dashboard), maker_left (paused when the teammate who made it left the workspace). null while it is on.

• created_at optional string

  Created At

• description optional string

  A label for people, such as the app that subscribed.

Responses

• 201 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.
• 409 too_many_endpoints: the workspace already has 10 webhooks; remove one first. idempotency_in_progress: the first request with this Idempotency-Key is still running.

curl -X POST https://www.bidii.ai/api/v2/webhooks \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "...", "events": ["..."]}'

DELETE /webhooks/{webhook_id}

Unsubscribe a webhook

Remove an endpoint and its delivery log; nothing more is sent to it. A key limited to some agents removes only the endpoints pinned to one of them. The endpoint a Build bot's webhook plugin sends through is the plugin's, and answers 404 here: disconnect the plugin instead.

Scope: webhooks:write

Parameters

• webhook_id required in the path · string

Responses

• 204 Successful Response
• 401 Missing, invalid, revoked or expired key. Leaving the workspace, or being removed from it, revokes the keys a teammate made; a key whose maker's membership ended any other way answers key_maker_left.
• 403 The plan has no API, the key lacks the scope, or the role of the teammate who made the key no longer allows it (maker_role_limit; a publishable key says insufficient_scope).
• 404 Nothing by that id in this workspace.
• 413 The request body is larger than this route accepts (1 MB; 3 MB for a text source). On a source: plan_text_limit, the agent's plan cannot hold more text (limit_chars, used_chars).
• 422 The request did not validate; details lists the fields.
• 429 Rate limit reached; wait Retry-After seconds.
• 500 Our fault; quote request_id to support.

curl -X DELETE https://www.bidii.ai/api/v2/webhooks/WEBHOOK_ID \
  -H "Authorization: Bearer bidi_sk_YOUR_KEY"