Webhooks

Creating a webhook#

Choose Create webhook. Only the name, the URL and at least one event are required.

Name#

A label for your own benefit, up to 200 characters. It appears in the list, in the events log, and in the notification you receive if the endpoint is ever auto-disabled — so name it after the system that consumes it, not after the events.

Endpoint URL#

Must be an https:// URL. In production the host must also resolve to a genuinely public address. These are rejected:

• Loopback addresses (127.0.0.0/8, ::1)
• Private and site-local ranges
• Link-local and multicast addresses
• The cloud metadata address 169.254.169.254

Basic authentication (optional)#

If your endpoint sits behind HTTP basic auth, expand this section and supply a username and password. They are sent as an Authorization: Basic … header on every delivery — in addition to the signature, not instead of it.

Choosing events#

Tick the objects you care about. Each expands to offer All actions — which keeps up automatically as new actions are added — or Specific actions, which pins the selection to exactly the ones you name.

The signing secret#

Creating a webhook generates a signing secret prefixed whsec_. It is displayed once and stored encrypted afterwards — no screen, endpoint or support process can show it to you again.

Events#

Events are selected as object.action and arrive with a camel-case event_name — the work_item.created selection delivers events named onWorkItemCreated.

Selecting All actions stores conversation.all rather than the individual actions, so an action added to that object in future starts arriving without you changing anything. If that is not what you want, pin the selection with Specific actions.

Full catalogue#

Three objects, twenty-three events.

What your endpoint receives#

Every delivery is a POST with Content-Type: application/json. The envelope is the same for every event; only data changes shape.

The envelope#

Headers#

Payload by event#

One entry per event: the fields it carries, and the exact JSON we post. The envelope is the same every time — only data and delta change shape — so it is described once in The envelope, and the request headers in Headers.

Values are illustrative. Ids, timestamps and phone numbers are examples, not fixtures to assert against — match on event_name and the field shapes, and treat unknown fields as additive.

Conversation#

Work Item#

Campaign#

Verifying the signature#

Anyone who learns your endpoint URL can post to it. The signature distinguishes a real delivery from a forged one, so verify it before acting on a payload.

The signed payload is the timestamp, a literal full stop, and the raw request body:

signed_payload = X-Bc-Timestamp + "." + raw_body
expected       = hex( HMAC_SHA256( key = whsec_…, message = signed_payload ) )

Compare expected with X-Bc-Signature.

// Node.js — note req.rawBody, not the parsed object
const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const ts  = headers["x-bc-timestamp"];
  const sig = headers["x-bc-signature"];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");

  const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
  const fresh = Math.abs(Date.now() / 1000 - Number(ts)) < 300;

  return ok && fresh;
}

# Python
import hmac, hashlib, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    ts  = headers["X-Bc-Timestamp"]
    sig = headers["X-Bc-Signature"]

    expected = hmac.new(
        secret.encode(),
        f"{ts}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()

    fresh = abs(time.time() - int(ts)) < 300
    return hmac.compare_digest(expected, sig) and fresh

Replay protection#

The signature covers the timestamp, so an attacker cannot alter it — but they could replay a captured request verbatim. Rejecting anything older than a few minutes closes that window.

Also compare in constant time — timingSafeEqual / compare_digest rather than ==, which leaks timing information that can be used to recover a valid signature.

Delivery & retries#

A delivery succeeds when your endpoint answers with any 2xx status. Anything else — including no response at all — is a failure.

Duplicates are expected#

Delivery is at-least-once, not exactly-once. A retry fires whenever success is not confirmed — including when your endpoint processed the event correctly but the response was lost. Your handler must tolerate seeing the same event twice.

Deduplicate on idempotency_key. It is unique per subscription per occurrence and constant across retries, which X-Bc-Delivery-Id deliberately is not — that changes on every attempt, which is what makes it useful in logs.

Re-sending a delivery#

There is a second way you may see the same event twice, and it is worth planning for. Someone on the BusinessChat side — you, or our support team — can manually re-send any delivery that did not succeed and has no further automatic attempt coming. That is a wider set than "it used up its retries", and it deliberately includes deliveries we never retried at all:

• one that exhausted its retries — all three attempts made, none successful;
• one rejected permanently on the first attempt — a 4xx outside the retryable set, which we never retry. Nothing further was ever going to be sent, so it is re-sendable straight away;
• one recorded as Blocked — see Blocked deliveries;
• one that ended Unknown — see Delivery statuses.

This usually happens once your endpoint has been fixed, which may be hours or days after the original event. A delivery that still has a retry scheduled is not offered — pressing then would only fire a send we were about to make anyway.

A manual re-send is an ordinary delivery in every respect that matters to your handler: same signature scheme, same headers, and the same idempotency_key as the original. So the deduplication above already covers it — if you have processed that key, drop it. Two things about it are worth knowing:

• It can arrive long after occurred_at. The payload is the one we captured at the time, so treat it as a record of what happened then, not as current state. If your handler needs the latest state, re-read it from the API rather than trusting an old payload.
• It can arrive out of order relative to events you have already received. Re-sends are made oldest-first, but they are still catching up on a backlog while live events continue to flow.

Some re-sent deliveries — the Unknown ones — were interrupted before we could record whether your endpoint answered, so we genuinely do not know whether you received them. Re-sending those is a deliberate choice made by whoever pressed the button, and the idempotency_key is precisely what makes it safe: a handler that deduplicates correctly sees no difference between a delivery it never got and one it has already processed.

Which button to use#

There are two, and they are not the same action at different scales. One sends a delivery now and tells you what happened; the other queues a set and tells you how many it took.

Retry this delivery — one delivery, and you see the answer

Expand a delivery in the events log and, if it can be re-sent, its latest attempt carries Retry this delivery. The send happens while you wait, so the page comes back with the status code your endpoint returned — a new attempt appears on the same delivery, carrying the same idempotency_key as the original.

Reach for it when you are dealing with one delivery, or when you want to confirm a fixed endpoint really answers before queueing a backlog at it. Deliveries that cannot be re-sent simply do not show the button — see Re-sending a delivery for which those are.

Retry all — one status, scoped to your filters

Select the Failed, Unknown or Blocked filter and a Retry all button appears above the table, carrying that chip’s count. It queues rather than sending inline, so it returns as soon as the batch is accepted rather than waiting on your endpoint.

• One status at a time. There is no “retry everything”: re-sending a confirmed failure and re-sending a delivery that may already have been processed are different decisions, so they stay different buttons. Under the Unknown filter the button asks for confirmation first, because those deliveries may already have reached you.
• It is scoped to the filters you have set — the date range, the event filter and the search box all narrow it. What it re-sends is what the list in front of you is showing, and the number on the button is that same filtered count.
• It may queue slightly fewer than the count. A delivery whose automatic retry is still scheduled is skipped: it is about to be sent anyway. That is the only reason the two numbers differ.
• Oldest first, in batches. One press takes as much as your per-minute delivery budget allows and reports how many remain, so a large backlog drains over several presses.

Blocked deliveries#

Immediately before each send, BusinessChat re-checks that your endpoint URL is still usable — that its hostname still resolves, that it resolves to a genuinely public address, and that it is still an https:// URL with no embedded credentials. If that check fails, the attempt is recorded as Blocked — we did not send it, and your endpoint never received it.

The usual cause is DNS. A record that has expired or been removed leaves the hostname unresolvable — a temporary tunnel that lapsed, a subdomain that was deleted, a domain that was not renewed — and every subsequent delivery to that subscription is blocked until it resolves again.

A blocked delivery is not retried. Nothing was sent, so waiting five minutes and sending the same request to the same unusable URL cannot produce a different answer; it is terminal on the first attempt. That is deliberate rather than a limitation: the delivery is finished, and therefore re-sendable, the moment you fix the endpoint — you are not waiting out a retry cycle first.

Blocked is also the one status you can re-send with no risk of a duplicate. A blocked delivery provably never reached your endpoint, so replaying it cannot deliver anything twice — unlike an Unknown attempt, where we genuinely cannot say. The recovery is therefore mechanical: restore the DNS record (or whatever made the URL unusable), confirm it with Test, then open the events log, filter to Blocked and press Retry all blocked. Deliveries are re-sent oldest first, and a large backlog drains over several presses.

What a blocked delivery tells you#

Expand a blocked attempt in the events log and its error message names the specific check that refused it. There are six, and they point at different fixes. {host} and {scheme} below are filled in with the values from your own endpoint URL.

We deliberately never print the address a hostname resolved to, only the hostname itself. The hostname is your own configuration and is what tells you which endpoint to fix; the resolved address would turn this message into a way of asking our network what any name resolves to inside it.

If you press Retry on a single blocked delivery while the endpoint is still unusable, the retry is refused straight away and says so: "This delivery's endpoint URL could not be used, most often because its DNS record is missing or expired. Fix the endpoint's DNS, then retry." Nothing is sent and no new attempt is recorded. Retry all blocked behaves differently — it queues the backlog first and each delivery meets the check individually, so against an endpoint that is still broken it reports a normal queued count and then records a fresh Blocked attempt for each one. Either way nothing reaches your endpoint. Fix the URL, confirm with Test, and only then retry.

Auto-disable#

If a subscription fails continuously for 24 hours with no successful delivery in between, it is switched to Auto-disabled and stops receiving events. Business admins are notified.

The clock is a continuous-failure timer, not a counter: a single 2xx clears it completely. To recover, fix the endpoint, use Test to confirm it answers, then re-enable the subscription.

An attempt that resolves to Unknown — see Delivery statuses — never touches this clock either way. It is a platform-side interruption, not evidence about your endpoint, so it neither starts the timer nor clears it.

An attempt that resolves to Blocked — see Blocked deliveries — does count. An endpoint URL we cannot use is exactly the endpoint this switch exists to stop sending to, so a subscription pointing at a hostname that no longer resolves runs the timer down like any other failure and is auto-disabled after 24 hours, with the same notification to business admins. This is new: a subscription failing this way used to be able to go on failing indefinitely without ever being switched off, and without appearing in the events log at all.

Monitoring deliveries#

The events log — the second icon on each row — opens a dedicated deliveries page for that subscription, listing every settled attempt newest first. Six chips filter the list — All, Succeeded, Failed, Unknown, Blocked and Retried — each showing its own count, alongside a date range, an event filter and a search box. Results are paginated — 25 rows per page by default, adjustable with the Rows per page control, with Previous and Next to move through the rest. There is no auto-refresh; a Refresh button re-runs the current filters on demand. An attempt that is still in flight joins the list as soon as it has an outcome, normally within seconds — see In-flight deliveries.

Each row that can be re-sent carries its own Retry — see Re-sending a delivery for which those are. Alongside it, Retry all re-sends in bulk, and it is worth being precise about what it acts on:

• It takes one status at a time — Failed, Unknown or Blocked. There is no "retry everything": re-sending a confirmed failure and re-sending a delivery that may already have been processed are separate decisions, so they stay separate buttons.
• It honours the filters you have set. The date range, the event filter and the search box all narrow what it re-sends, so it acts on the deliveries the list is showing you rather than on the whole subscription. The count on the button is that same filtered number.
• It may still queue slightly fewer than the count. A delivery whose automatic retry is already scheduled is left alone — it is about to be sent anyway — so it is counted in the list but skipped here. That is the only reason the two numbers differ.
• It works oldest-first, in batches. One press queues as much as the business's per-minute delivery budget allows and reports how many remain; a large backlog drains over several presses.

Delivery statuses#

Every attempt is exactly one of five statuses. They are mutually exclusive and exhaustive, and ?status= on the API accepts all five — pending, succeeded, failed, blocked and unknown. Four of them are outcomes, and those are what the events log in the dashboard shows. pending is not an outcome — it means the attempt has not finished yet — and it is reported by the API only.

In-flight deliveries#

The events log lists outcomes: succeeded, failed, blocked and unknown. An attempt that is still being sent — status pending — is left out of the list and has no filter of its own, because there is nothing yet to read and nothing to do about it. It appears with the rest as soon as your endpoint answers or the attempt times out, which is at most 15 seconds later (5 to connect, 10 to respond). Refresh, or reopen the log.

The API is different, on purpose. GET /admin/webhook-deliveries returns in-flight deliveries alongside settled ones and honours ?status=pending, so an integrator building a dashboard, or our support team looking at a subscription mid-burst, can still see what is happening right now. If you are reconciling API results against the events log, that is the difference between them: the API reports the whole table, the dashboard reports the part that has finished.

Expanding a delivery shows its Request ID, idempotency key and request payload once, above the timeline; each attempt below is collapsed to a single line by default, and expanding one reveals that attempt's own response body and error.

The Request ID identifies the delivery, not a single attempt — it stays the same across every attempt in a retry chain, as in the example above, and is the right thing to quote when asking support about it. Each attempt also carries its own X-Bc-Delivery-Id header, which does change between retries — see Headers.

History retention#

The events log covers the current and previous calendar month; delivery attempts older than that are removed and cannot be recovered. Because the cutoff is a calendar boundary rather than a rolling window, how far back it actually reaches depends on the date: a little over 30 days on the 1st of the month, close to 60 by the last day of the month. It is not a flat “30 days,” even though the longest date-range preset reads 30d — that preset stops there because 30 days is the longest window we can promise is always inside the retained history. A longer fixed preset would sometimes be honest and sometimes silently miss the oldest attempts, depending on the day it was clicked.

Deleting a subscription does not delete its delivery history. Past attempts stay visible in the events log, subject to the same retention above, under a “This webhook no longer exists” heading in place of the subscription's name. This is deliberate: the record of what was sent and received is kept for as long as retention allows, even after the subscription itself is gone.

Testing an endpoint#

The Test action sends a webhook.test event immediately, signed with the real secret, in the identical envelope shape a real event uses. If your handler can parse and verify the test, it can parse and verify everything else.

Test sends appear in the events log alongside real ones, named webhook.test. They are sent once and never retried, so a failed test does not start a retry cycle or count towards auto-disable.

Managing a webhook#

Enabling and disabling#

The Enabled toggle stops and starts delivery without losing the subscription, its secret, or its history. Events that occur while it is off are not queued and are not backfilled.

Editing#

Deleting#

Troubleshooting#

Deep-link anchors#

Every id below is part of this document's public contract. They are hand-written, not derived from heading text, so rewording a heading will not break an existing link. Treat them as permanent: link to them from the product UI, from support macros, from anywhere.

Rules for adding anchors#

• Ids are kebab-case and describe the topic, not the wording of the heading.
• Prefix sub-section ids with their parent (delivery-auto-disable) so the hierarchy is readable from the link alone.
• Never remove or repurpose an id. If a section is dropped, leave the id on whatever replaced it, or on its nearest surviving parent.
• Add the id to the table above in the same change, so this list stays the single place to look.