Event webhooks for your account's activity

When you're done, another app, such as Zapier, Make or your own server, hears about what happens in your account as it happens.

Who can do this: the account owner on Business. On other plans, Settings says "Event webhooks for everything in your account (new leads, publishing, workspaces, handoffs, usage and key problems) come with the Business plan."

The events

Event	When it's sent
New lead	"Someone filled in a lead form on any Chirp or Collection."
Chirp published	"A Chirp became public or unlisted (or came back from the archive)."
Chirp unpublished	"A Chirp went back to draft or was archived."
Workspace created	"A new workspace was added to the account."
Handoff completed	"A client accepted a workspace you handed over."
Usage threshold reached	"This month's messages reached the number you set (once a month)."
OpenRouter key problem	"An account or workspace OpenRouter key stopped working (invalid, out of credit or unreachable)."

To send only new leads to one form's own list, a lead webhook may suit you better: see Send leads to Zapier or a webhook.

Add a webhook

1. Open Settings and find Event webhooks.
2. Under Add a webhook address, paste the address (1). It must start with https://.
3. Click the events you want (2). New lead is picked to start with. For Usage threshold reached, fill in "Usage alert at … messages a month".
4. With more than one workspace, you can pick workspaces under "Only these workspaces (leave empty for all):" (3).
5. Click Add webhook (4): "Webhook added. Verify it to start getting events."
6. Copy the Signing secret (shown once) with Copy. It's never shown again.

Verify it

A new webhook says "Not verified: gets no events yet". Click Verify now. Chirp Builder sends it a webhook.verification event, and your address must answer with any 2xx status within 10 seconds: "Verified. It gets events from now on." Events that happen before then aren't sent later.

Check it's working

• Verified (1) means it gets events.
• Send a test (2) sends a sample of the first event the webhook has picked, right away: "Test sent".
• Delivery log (…) lists its last 20 deliveries: Sent, Waiting, Retrying at a time, or Failed, with the event, when, how many tries, the error and the event id. Tests say "(test)".
• Send again (3) on a failed or retrying delivery sends it now.

To change a webhook, click its event or workspace names (it saves straight away; the last event can't be removed), use its switch to turn it off and on ("Switched off", "Switched on"), or click the trash button and confirm "Remove this webhook? It stops getting events." You can't change the address: remove the webhook and add it again, which also gives you a new secret.

What your server receives

A POST with a JSON body { id, type, created_at, workspace: { id, name } | null, data }. The id is the event id: "the same event never gets a different one, so you can skip repeats." workspace is null for handoffs, usage alerts, problems with your account's key, tests and verification.

The headers include X-Chirp-Event, X-Chirp-Event-Id, X-Chirp-Delivery, X-Chirp-Timestamp (Unix time in seconds) and X-Chirp-Signature: sha256=…: an HMAC-SHA256 of the timestamp, a dot and the body, made with the whole signing secret (starting whsec_) as the key. It's the same scheme as lead webhooks.

What's in data, by type:

• lead.created: lead (id, email, name, wants_updates, consent, captured_at) and source (type "chirp" or "collection", id, name).
• chirp.published and chirp.unpublished: chirp (id, name, slug, visibility, archived).
• workspace.created: workspace (id, name).
• workspace.handoff_completed: handoff (id, workspace_name, to_email, accepted_at, and how many chirps, collections and leads moved).
• usage.threshold_reached: usage (threshold, messages, month as YYYY-MM).
• key.failed: key (scope "account" or "workspace", last4, status "invalid", "no_credits" or "error", and detail).

Tests add "test": true to data.

Retries

"Answer with any 2xx within 10 seconds. Anything else is tried again after 1 minute, 5, 30, 2 hours and 6 hours." That's up to 6 tries. Retries go out every 5 minutes, so one can arrive a few minutes after its time. Redirects aren't followed.

Good to know

• Up to 10 webhook addresses per account.
• Workspaces: with none picked, a webhook gets events from every workspace. Account events (handoffs, usage alerts, your account key) always come. If a webhook's last picked workspace is deleted or handed over, the webhook is switched off.
• Usage threshold: counts this calendar month's messages (in UTC) in all your workspaces, without preview chats in the builder (yours and your team's), and is sent once, when the count reaches your number.
• OpenRouter key problem is sent when a key that was Connected stops working.
• Workspace created isn't sent for a workspace a client handed over to you.
• Off Business, nothing is sent. Your webhooks stay listed, and switching them on, verifying, testing or changing their events shows the Business message.
• The delivery log keeps 30 days.

If it doesn't work

• "Paste the full webhook address, starting with https://" or "The webhook address must start with https://"
• "Use a public web address (not an IP address or a local one)", "That address points to a private network. Use a public webhook address." or "That address couldn't be found. Check the webhook address."
• "Leave the user name and password out of the address", "Use the normal https port" or "That address is too long"
• "Pick at least one event." or "Set the number of messages for the usage alert."
• "You can have up to 10 webhook addresses."
• "Not verified yet." followed by the reason, for example "The address didn't answer within 10 seconds.", "Couldn't reach the address.", "The address redirected. Use the final address." or "It answered 404" with the start of its reply.
• "The webhook is switched off." in the log: switch it on, then click Send again.
• "Couldn't save the webhook."