Make a webhook

BlueBot posts each event of the types you choose to url, signed the Standard Webhooks way with the secret in the answer, which is shown this once. A delivery that fails is tried again for about 3 days; after 72 hours with no 2xx the webhook is paused and you are emailed. Answering 410 deletes it.

Needs a key with the webhooks:manage scope. Keys and scopes

Send an Idempotency-Key so a retry never acts twice. Idempotency

Headers

• Idempotency-Keystring

  Any string of up to 255 characters, new for each request. A retry with the same key gets the first answer back for 24 hours, with Idempotent-Replayed: true.

  Up to 255 characters.

Request body

• urlstringrequired

  An https address on the public internet. BlueBot doesn’t follow redirects.

  Up to 2,048 characters.

• eventsarray of anyrequired

  The event types to send, or ["*"] for every type, including types BlueBot adds later.

• descriptionstring

  Up to 200 characters.

Example

curl -X POST "https://usebluebot.com/api/v1/webhooks" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 0f6d8c2e-5b1a-4c7e-9d3f-2a8b6e1c4d70" \
  -d '{
    "url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/",
    "events": [
      "message.received",
      "message.failed"
    ],
    "description": "New replies to my CRM"
  }'

Response

201: The webhook, with its signing secret.

• idstringrequired

  A wh_ id.

  Starts with wh_.

• object"webhook"required
• urlstringrequired
• descriptionstring or nullrequired
• eventsarray of stringsrequired

  The event types it receives. For a webhook made with ["*"], every type there is now.

  One of message.queued, message.sent, message.delivered, message.read, message.failed, message.unconfirmed, message.expired, message.canceled, message.received, message.edited, message.unsent, reaction.added, reaction.removed, chat.created, contact.created, contact.stopped, contact.unstopped, sequence.completed, broadcast.completed, automation.matched, device.online, device.offline, device.check_failed.

• all_eventsbooleanrequired

  True when it was made with ["*"]: it also receives event types BlueBot adds later.

• api_versionstringrequired

  The payload version it was made with and keeps.

• statusstringrequired

  active; failing while deliveries fail (retried for about 3 days); paused by you, or after 72 hours with no successful answer.

  One of active, failing, paused.

• paused_attimestamp or nullrequired

  When it was paused.

• pause_reasonstring or nullrequired

  Who paused it: failing (72 hours of failures), customer or staff.

  One of failing, customer, staff.

• failing_sincetimestamp or nullrequired

  The first failure since the last success.

• last_success_attimestamp or nullrequired

  The last delivery answered with a 2xx.

• last_failure_attimestamp or nullrequired

  The last delivery that failed.

• last_statusinteger or nullrequired

  The HTTP status of the last answer.

• previous_secret_expires_attimestamp or nullrequired

  After a rotation, when the old secret stops signing alongside the new one.

• created_attimestamprequired

  When it was made.

• secretstringrequired

  The signing secret, whsec_ and base64. Verify webhook-signature with it. Shown when the webhook is made and when the secret is rotated.

{
  "id": "wh_1Hq2LxW9cVbN3mKpRtYs0a",
  "object": "webhook",
  "url": "https://hooks.zapier.com/hooks/standard/1234567/abcdef/",
  "description": "New replies to my CRM",
  "events": [
    "message.received",
    "message.failed"
  ],
  "all_events": false,
  "api_version": "2026-11-13",
  "status": "active",
  "paused_at": null,
  "pause_reason": null,
  "failing_since": null,
  "last_success_at": null,
  "last_failure_at": null,
  "last_status": null,
  "previous_secret_expires_at": null,
  "created_at": "2026-11-01T15:10:00.000Z",
  "secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
}

Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

Try it