A chatbot webhook is an HTTP endpoint on your side that receives a message when something happens, such as a new chat, a captured lead or a low satisfaction rating. Your system can then act on it: create a ticket, update a CRM record or send data back into the conversation. Set it up with a public HTTPS URL, verify every signature, and return a fast 2xx response. Everything slow happens after that.
This guide covers the mechanics, a step-by-step setup, the security checklist, and the part most tutorials skip: how webhook latency and failures show up in the chat widget your customers see.
TL;DR
- A webhook is the provider calling you when an event happens. An API call is you asking the provider. Most chatbot integrations use both.
- Set up means: a public HTTPS endpoint, selected event types, a stored signing secret, signature checks, and a 2xx response returned quickly.
- Keep the handler fast: acknowledge first, queue the work, and make processing idempotent because retries will send duplicates.
- A slow webhook that the bot waits on is a slow chat. Move anything heavy out of the live reply path.
- Webhooks are not replaced. Polling, streaming and message queues complement them for specific cases.
Table of Contents
- What a chatbot webhook is
- Webhook vs. API call
- Customer service examples that earn their keep
- How to set up a chatbot webhook, step by step
- Security and reliability checklist
- Latency, timeouts and chat widget performance
- Have webhooks been replaced?
- Our perspective
- Connect your chatbot to your stack with Monobot
- FAQ
- Sources
What a chatbot webhook is
Twilio’s documentation defines a webhook as an HTTP or HTTPS callback sent to your application after a specified event occurs. Your application does not ask for anything. The platform pushes the event to a URL you registered.
In a chatbot, those events are usually:
- a conversation starts or ends;
- a visitor shares an email address or phone number;
- the bot reaches a point it cannot resolve and hands off to a person;
- a customer leaves a satisfaction rating;
- a transcript becomes available.
The payload is typically JSON. According to one guide to chat webhooks, payloads can carry visitor names and email addresses, transcripts and satisfaction ratings, which is what makes low-rating follow-ups and analytics logging possible.
There is a second pattern worth separating: a webhook the bot calls in the middle of a conversation. For example, the visitor asks “where is my order?”, the bot sends the order number to your endpoint, and your endpoint returns the status for the bot to read out. The first pattern is a notification. The second is a lookup, and it is the one that affects how fast your chat feels.
Webhook vs. API call
The difference is who starts the conversation. Zapier puts it simply: a webhook is an endpoint that sends information when a trigger occurs, without another app requesting it, whereas an API request is made by your app to get or change something. Twilio frames the same split: its REST API handles requests your application initiates, while webhooks are what Twilio sends to your application.
| Webhook | API call | |
|---|---|---|
| Who starts it | The platform, on an event | Your application |
| Timing | Event-driven, asynchronous | On demand |
| Typical chatbot use | New lead, handoff, rating, transcript ready | Fetch a customer record, create a ticket, send a message |
| Your responsibility | Receive, verify, acknowledge | Authenticate, handle errors and rate limits |
| Failure mode | Missed or duplicated events | Failed or slow request |
In practice you use both. A webhook tells your system that a lead was qualified. Your system then makes API calls to the CRM to create the contact. If you are mapping those downstream systems, our overview of types of CRM integrations for chatbots shows how the pieces fit.
Customer service examples that earn their keep
Start with the events that save a human a manual step.
- Lead capture to CRM. When the bot qualifies a visitor, the webhook creates the contact and assigns an owner. Zapier notes webhooks can notify teams about new leads or support tickets.
- Order status lookup. The bot passes an order ID to your endpoint and reads back the status. This is the in-conversation pattern, so it needs to be fast.
- Appointment booking. The bot sends a requested slot, your scheduling system confirms or offers alternatives, and the bot relays the result.
- Escalation with context. On handoff, the webhook posts the transcript and customer details to your helpdesk so the agent does not start from zero. Our guide to Zendesk chatbot integration paths walks through options for this.
- Low-rating alerts. A rating below your threshold posts to a team channel or opens a follow-up task.
- Analytics logging. Every finished conversation is written to your warehouse so you can measure containment and resolution over time.
If you want a broader view of chaining these steps together, see how workflow automation AI agents handle multi-step voice and chat tasks. For the surrounding process, a marketing automation checklist is a handy reference for deciding which chatbot events should feed which tools.
How to set up a chatbot webhook, step by step
The sequence below follows the pattern OpenAI documents for its own webhooks, and most providers work the same way. It is a sound template: create an endpoint with a public URL, choose event types, save the signing secret, then handle POST payloads, verify signatures and return a 2xx quickly.
1. Decide which events you need
Subscribe only to what you will act on. Each extra event type is traffic to receive, secure and monitor. A support team usually needs handoff, conversation ended and rating. A sales team needs lead captured and appointment booked.
2. Build a public HTTPS endpoint
The endpoint must be reachable from the provider’s servers, so localhost will not do. During development, use a tunneling tool to expose a local port, then switch to a deployed URL. Require HTTPS from day one: transcripts and contact details travel in these payloads.
3. Register the URL and store the secret
In the platform’s settings, add the URL and pick your event types. The provider issues a signing secret. Keep it server-side, in a secrets manager or environment variable, never in front-end code or a repository.
4. Verify the signature before anything else
Compute the signature of the raw request body with your secret and compare it with the header the provider sends. Reject anything that does not match. Without this step, anyone who finds your URL can post fake events into your CRM.
5. Acknowledge fast, process later
Return a 2xx as soon as the signature checks out and the event is saved or queued. Then do the real work in a background worker. This is the single habit that prevents most webhook trouble, and the next sections explain why.
6. Make processing idempotent
Store each event’s ID and skip ones you have already handled. Providers retry on failure, so duplicates are normal rather than exceptional.
7. Test with failures, not just successes
Send a bad signature, a malformed body, a duplicate and a slow response. Confirm each behaves the way you intend before real customers are on the other side.
Security and reliability checklist
Treat the endpoint as a public door into systems that hold customer data.
- Use HTTPS only. Chat transcripts and personal identifiers should never cross the network in clear text.
- Verify signatures with a secret kept server-side, and rotate the secret if it is ever exposed, as OpenAI’s guidance advises.
- Respond quickly with 2xx. The same guidance notes that failed or slow deliveries are retried with exponential backoff.
- Minimize the payload you store. Keep what you need for the follow-up action, and apply your own retention rules to transcripts.
- Log every delivery with event ID, status and processing time, so you can answer “did that lead reach the CRM?” in seconds.
- Alert on failure rates, not individual errors. A sudden rise in non-2xx responses usually means a deploy broke something.
If your chatbot handles protected health information, the platform tier matters as much as your endpoint. Our pricing page lists HIPAA support as a separate monthly line item, so check it before you route clinical conversations anywhere.
Latency, timeouts and chat widget performance
This is where webhook design becomes something your customers feel.
Most providers give your endpoint a limited window. One guide on webhook timeout practices says providers typically allow somewhere between 5 and 30 seconds before treating a delivery as failed, and recommends answering in well under a second by verifying the signature, queuing the event and returning 200. A timeout counts as a failed delivery, so the same event comes back on the retry schedule.
Two different performance problems follow from that.
Notification webhooks (after the fact). If your handler is slow, the chat itself is not affected, but you get retries, duplicates and a growing backlog. The fix is the acknowledge-first pattern above.
Lookup webhooks (mid-conversation). Here the bot waits for your answer before replying. Every millisecond of your endpoint is added to the visitor’s wait, on top of the language model and, for voice, speech-to-text and text-to-speech. A chat widget that shows a typing indicator for eight seconds feels broken even when it eventually answers correctly. On a voice call, silence is worse.
What helps:
- Keep lookups narrow. Return only the fields the bot needs to say the answer, not a whole customer object.
- Cache stable data. Store hours, product catalog entries and plan names do not need a database query every time.
- Set your own timeout shorter than the platform’s, and give the bot a graceful fallback: “I can’t reach order status right now, want me to have someone email you?”
- Move slow work out of the reply. If creating a ticket takes four seconds, tell the customer it is created and confirm by email, instead of holding the conversation.
- Measure end to end. Track the time from the visitor’s message to the bot’s reply, and break out the webhook’s share. Dashboards that show per-step timing make this obvious; see our dashboard analytics for the kind of conversation-level reporting that helps.
The widget itself also matters. A lightweight embed that loads asynchronously keeps your page speed intact, so the webhook is the only part left to tune.
Have webhooks been replaced?
No. People ask because newer tools exist, but each solves a different problem.
| Approach | Best when | Trade-off |
|---|---|---|
| Webhooks | You want to be told about discrete events with low overhead | You must host a reliable endpoint and handle retries |
| Polling | The provider offers no webhook, or you need to reconcile state on a schedule | Wasteful and delayed, since most checks find nothing new |
| Event streaming or message queues | High event volume, multiple consumers, ordered processing | More infrastructure to run and learn |
| Scheduled batch export | Reporting where minutes of delay do not matter | Not suitable for live follow-up |
A common mature design uses a webhook as the front door, drops the event on a queue, and lets several workers consume it. You get the simplicity of a push with the durability of a queue. Many teams also run a nightly poll to reconcile anything a missed webhook dropped. That is belt and suspenders, and it is reasonable for revenue-critical flows.
If you do not want to write any code, no-code automation tools can receive a webhook and fan it out to dozens of apps. That works well for low-volume flows. When volume or latency requirements grow, move the critical path to your own endpoint.
Our perspective
We see the same mistake across customer service deployments: teams treat the webhook as the integration, when it is only the doorway. The integration is what happens behind it, and the best ones are boring. Fast acknowledgment, a queue, clear logs, one owner.
At Monobot we build voice and chat agents so that teams can launch without writing code, often within minutes, and connect them to the systems they already run. Our view is that the bot should handle routine work, such as scheduling, order status, inquiries and lead qualification, and that anything needing your own data should go through a narrow, quick lookup. We would rather a bot say “let me get someone” in two seconds than fumble for ten.
Our advice for a first project: pick one event, one downstream system and one metric. Ship it, watch the delivery logs for a week, then add the next. Complexity you add after the first flow is stable is far cheaper than complexity you debug in a tangle. And keep humans in the loop: real-time assistance and clean handoffs matter more than squeezing out the last percent of automation.
— Alex
Connect your chatbot to your stack with Monobot
If you would rather configure integrations than build them from scratch, Monobot’s Integration Hub connects our voice and chat agents to CRMs, helpdesks and other business tools. You can start from ready-to-use templates for healthcare, banking, retail, logistics and more, then adjust flows without code.
Plans are published on our pricing page: Starter is $200 per month, Growth is $500 per month and Business is $1000 per month, with Enterprise available on request. Each phone number adds $2.5 per month. Not sure which fits? Schedule a demo and we will map your first webhook flow with you.
FAQ
What is a webhook in a chatbot?
It is a URL on your server that the chatbot platform calls when an event occurs, such as a new lead or a handoff to an agent. The platform sends the event data, usually as JSON, and your system acts on it. Some webhooks also return data the bot uses in its next reply.
What is the difference between a webhook and an API call?
With an API call, your application asks the platform for something. With a webhook, the platform tells your application something happened, without being asked. Most chatbot integrations combine both: the webhook signals the event, and API calls update your other systems.
Why is my chatbot slow when it uses a webhook?
If the bot waits for your endpoint before replying, your endpoint’s response time is added to every answer. Slow database queries, large payloads and chained API calls are the usual causes. Shorten the lookup, cache stable data, set a timeout with a fallback message, and move heavy work to a background process.
Are webhooks safe for customer data?
They can be, if you require HTTPS, verify signatures with a server-side secret, store as little as you need and log every delivery. Payloads often contain names, emails and transcripts, so treat the endpoint like any other system that holds personal data.
Do I need to write code to use webhooks?
To receive them on your own server, yes, a small amount. To connect a chatbot to common business tools without code, use an integration layer or automation platform that receives the webhook for you.
Sources
- Webhooks Overview | Twilio
- Webhook vs. API: Differences and when to use each | Zapier
- Webhooks | OpenAI API
- A Guide to Chat Webhooks: Connecting Live Chat to Your Tools
- Webhook Timeout Best Practices | Svix
- Marketing Automation Checklist: Step-by-Step Guide for SMBs