Handle what it brings you
Send bot events to a webhook
When you finish, events like a new lead land in your own system within about a minute, signed so you can tell they came from us.
Before you start
- Your account is on the Scale or Advanced plan. How to check
- You have an HTTPS address that can receive a POST. Your developer, or a tool like Zapier, gives you one.
- Someone can check what arrives there. A webhook only earns its place if something reads it.
About 10 minutes. You’ll do four things:
- add the destination
- save the signing secret
- switch on the events you want
- send a test
A webhook is a message we send to your system when something happens in your chat. A visitor leaves their details, and the lead is in your CRM about a minute later — usually before you have read the email about it.
The eight things we can tell you about
| Event name | What just happened |
|---|---|
| new_lead | A visitor filled in the lead form and left their contact details. |
| escalation | A chat was handed over to a person, a WhatsApp handoff for example. |
| negative_feedback | A visitor gave one of the bot's replies a thumbs-down. |
| knowledge_gap | The same question keeps coming up and the bot keeps failing to answer it. |
| stale_source | Something you trained the bot on has not been refreshed in a while. |
| cap_approaching | Your account has used around 90% of this month's message credits. |
| billing_failure | A subscription payment failed. |
| subscription_cancelled | A paid plan ended and the account went back to Free. |
The other case is a system you or your developer look after, which should hear about events directly. That is what a destination does.
A worked example: a new lead in your CRM
Say you want every new lead in your CRM the moment it lands. The chain is short:
- A visitor leaves their name and email in the chat.
- We send a signed message to the address you add below, within about a minute.
- Your CRM, or a Zap sitting in front of it, creates the contact.
- The same lead is still on the bot's Leads page, so nothing is lost if your end is down.
| Option | Best for |
|---|---|
| Workspace | Everything in the account. Events from every bot, plus the billing, credit and stale-source events that belong to no single bot. |
| Bot | One bot only. You get that bot's leads, escalations and feedback, and nothing from the others or from billing. |
Add a destination
In Workspace settings, click Webhooks.
Click Add webhook destination.
In Label, type a name you will recognise in six months.
Up to 80 characters. Something like: Zapier lead catcher.
In URL, paste the address that will receive the events.
It has to start with https://. A plain http:// address is refused.
In Scope, choose the option you picked above.
Click Save.
Save the signing secret
Copy the secret out of the amber panel and store it where your receiver can read it.
The panel says it plainly: This is the only time the secret is shown. Store it now — it cannot be retrieved later.
Click I’ve copied this to close the panel.
Switch on the events you want
In Workspace settings, click Notifications.
Find the Webhook column.
Its boxes only tick once a destination exists. Before that the column header carries a Set up a destination first link instead.
Tick the Webhook box on every row you want sent.
Some rows are ticked already. Untick one and we stop sending that event to your destinations.
Prove it works
Back on Webhooks, click Log on your destination's row.
Click Send test event.
One a minute, per destination. Faster than that and the page says Try again in a minute.
Wait about a minute and watch the table.
It refreshes itself every half a minute. The row's Completed column turns success once your endpoint answered.
Where your developer takes over
Whoever builds the receiver needs one more page: the webhook delivery reference. It carries the headers, the signature, the shape of all eight payloads and a verifier they can copy. The same link sits at the top of the Webhooks page, as Read the delivery reference.
If it didn’t work
The Webhooks page shows an upgrade panel instead of the form
- Check
- It reads Outbound webhooks are available on the Scale and Advanced plans. and names your current plan underneath.
- Fix
- Click View plans and move to Scale or Advanced. On Free, Local or Growth nothing goes out, and the Zapier app cannot subscribe either.
- Resolved when
- The page shows the Add webhook destination button and the destinations table.
The Webhook column on Notifications will not tick
- Check
- The boxes are greyed out and the Webhook column header carries a link saying why. Set up a destination first means no destination exists yet.
- Fix
- Follow that link, add a destination, then come back. If the header link reads Upgrade instead, the plan is the blocker rather than the destination, and the greyed box says so on hover: Upgrade to enable webhook alerts.
- Resolved when
- The Webhook boxes tick, and the page says Saved.
The test event arrived but real events never do
- Check
- A test event goes straight to your destination and ignores Notifications entirely, so it proves the address, not the settings.
- Fix
- Open Workspace settings → Notifications and tick the Webhook box on the rows you want. Also check the scope: a destination scoped to one bot never gets the account-wide events, which are billing, credits and stale sources.
- Resolved when
- A real event, not test_event, appears in the Log marked success.
The log shows failed with a status code
- Check
- Open Log and read the Status code and Error category columns on the failed row.
- Fix
- A 4xx means your endpoint turned us away, usually a wrong path or a signature check that does not match. A 5xx or a timeout means your server was busy. Fix your end, then click Replay on that row.
- Resolved when
- Completed reads success on the replayed row.
I lost the signing secret
- Check
- There is no way to read it back. The panel that showed it said so at the time.
- Fix
- Click Rotate on that destination. You get a new secret, and the previous one keeps working for 24 hours so your receiver can be updated without a gap. Revoke kills the old one immediately instead.
- Resolved when
- Your receiver verifies with the new secret and the Log shows success.
There are rows I never added, named Zapier: something
- Check
- Any destination whose label starts with Zapier: was created by the Adoomi Zapier app when you switched a Zap on.
- Fix
- Turn that Zap off in Zapier and the row goes quiet on its own. Deleting the row here breaks the Zap rather than tidying it, so make the change in Zapier.
- Resolved when
- The Zapier rows match the Zaps you actually have running.
What this can’t do
- Webhooks are on the Scale and Advanced plans. On Free, Local or Growth nothing is sent, and the Zapier app cannot subscribe either.
- HTTPS only. An http:// address is refused with Webhook URL must use https://.
- A destination scoped to one bot never receives the account-wide events: billing failures, the credit-cap warning, stale sources and a cancelled subscription.
- The signing secret is shown once. Lose it and Rotate is the only route, which retires the old secret after 24 hours.
- Only failed deliveries can be replayed. Replay is greyed out on a delivery that succeeded or is still pending.
- A cancelled subscription has no row on the Notifications page, so it reaches every active account-wide destination and cannot be switched off there.