Integration · Developer tools
WhatsApp webhooks in Broadchat: receive events and trigger messages from any system
How Broadchat's inbound webhooks (workflow and chatbot triggers) and outbound webhooks (channel events, ecommerce, payments, widget) work, with payloads, mapping and fixes.
By Broadchat teamPublished 6 min read
You will need
- The Automations module on your plan for workflow webhooks, or the Chatbots module for the chatbot Inbound Webhook trigger (ask your provider if a menu is missing).
- A connected WhatsApp channel with at least one approved message template, if the webhook should send a message outside the 24-hour window.
- A system that can make an HTTP request: your website backend, a form tool, a CRM, a store plugin or an automation service.
- For outbound webhooks, an HTTPS endpoint on your side that answers within a few seconds.
What you can do with webhooks in Broadchat
A webhook is an HTTP request one system sends to another when something happens. Broadchat's WhatsApp webhook integration works in both directions. Inbound, your website, store, CRM or form tool calls a Broadchat URL and a workflow or chatbot sends the right WhatsApp message. Outbound, Broadchat calls your URL when a customer writes, a message is delivered, an order is placed or a payment completes.
This is the integration to use when there is no native connector for your software. Anything that can make an HTTP request can start a WhatsApp message, as long as the customer opted in and you use an approved template outside the 24-hour window.
Inbound: from your system to WhatsApp
A website enquiry form posts this JSON to the workflow's Webhook URL:
{
"name": "Priya Sharma",
"phone": "919876543210",
"interest": "3 BHK at Skyline Greens",
"enquiry_id": "ENQ-58214"
}The query string and the body are merged into one object, so each field is available as {{1.<field>}}, where 1 is the trigger step. The mapping for the enquiry_received_ack template from the lead follow-up templates is:
| Send Template Message (V2) field | Value |
|---|---|
| WhatsApp Number | {{1.phone}} |
| Template variable 1 | {{1.name}} |
| Template variable 2 | {{1.interest}} |
| Template variable 3 | {{1.enquiry_id}} |
Broadchat answers the caller with {"accepted":true,"runId":"..."} and runs the workflow in the background. Add Create / Update Contact before the send step if you also want the lead saved in CRM → Contact with custom fields.
Outbound: from Broadchat to your system
| Where | Events | Body |
|---|---|---|
| Channels → your channel → Webhooks | Incoming messages, sent, delivered, read, failed, deleted, template, phone number and account updates | Meta's webhook format, one change per request |
| Ecommerce → Trigger | Order Created, Order Updated, Product Created, Product Updated, Abandoned Cart Created | { event, trigger, data, sent_at } |
| Payments → Automations | New Payment Order Created, Transaction Completed, Transaction Fail | { event, eventLabel, timestamp, paymentOrder } |
| Chat Widget → Widget → Webhook | Widget session start and end, with pre-chat answers | { event, widget, timestamp, lead } |
Each request carries headers such as X-Webhook-Event, X-Webhook-Id and X-Webhook-Timestamp, and channel webhooks add X-Webhook-Channel-Id. Use the event header to route requests in your code. An incoming WhatsApp message forwarded from a channel looks like Meta's own payload, so code written for the Cloud API webhook can read it unchanged.
Troubleshooting
- 404 "invalid flow": the hook was regenerated or the workflow deleted. Copy the current Webhook URL again.
- 409 "workflow is inactive": switch the workflow to Active and save.
- The message does not arrive: check the run history. The number needs the country code (919876543210, not 9876543210), the template must be approved for that channel, and the number of mapped variables must match the template.
- Empty variables: map
{{1.name}}, not{{1.body.name}}. Only use abodypath if your sender's JSON really has abodykey. - Your endpoint misses events: outbound webhooks are not retried. Return a 2xx response within the timeout and do slow work after responding.
For sending from your own code without a workflow, see the Broadchat REST API. For what to send, browse the WhatsApp template library, and read the WhatsApp message templates guide for the rules. Agencies can offer webhook automations to clients under their own brand through the white-label platform.
Set it up
Create a workflow
Open Automations → Workflow and click Create Workflow. Broadchat creates an Untitled workflow and opens the builder. Rename it after what it does, for example "Website enquiry → WhatsApp".
Add the Custom Webhook trigger
Add the Webhook app and choose its Custom Webhook trigger. Enter a Webhook Title and click + Generate Hook. Copy the Webhook URL, which looks like https://<your panel domain>/api/automations/hook/<token>.
Capture a sample request
Click Capture Incoming Webhook, then send one real request from your system to the URL. When it arrives, click Show Received Data. The sample is stored for mapping and does not run the workflow.
Add the WhatsApp step
Add the CRM app's Send Template Message (V2) action. Choose Select Channel and Select Template, then map WhatsApp Number and each template variable to fields from step 1, for example {{1.phone}} and {{1.name}}.
Activate and test
Save the workflow and switch it to Active. Send another request and check the run in the workflow's history. An inactive workflow answers 409 "workflow is inactive".
Send events out (optional)
To receive WhatsApp events on your server, open Channels, open your channel, go to the Webhooks tab and click Add Webhook. Enter a Title, an https URL and tick the Channel Events you need, such as Incoming Messages and Delivered.
What you can do
Start a WhatsApp workflow from any system
The Custom Webhook URL accepts GET, POST, PUT, PATCH and DELETE with JSON, form-encoded or multipart bodies up to 1 MB, so most form builders, stores and CRMs can call it.
Start a chatbot conversation
The chatbot Inbound Webhook trigger starts a bot flow for a phone number in the payload, creating the contact if it does not exist. Useful when a form submission should open an interactive chat.
Forward channel events
Channel webhooks forward incoming messages, message statuses (sent, delivered, read, failed, deleted) and template, phone number and account updates in Meta's own webhook format.
Forward store and payment events
Ecommerce → Trigger posts order, product and cart events, and Payments → Automations posts payment order events, to any URL you choose, including another workflow's webhook.
Reply to the caller
A Data Forwarder step at the end of a workflow can return a custom JSON or HTML response, or a redirect, to the system that called the webhook.
Limitations to know
- Inbound workflow webhooks have no signature or header check: the secret token in the URL is the only credential. Keep the URL private and click Re-Generate Hook if it leaks (the old URL stops working).
- Outbound webhooks are sent once with a short timeout (5 seconds for channel and widget webhooks, 10 seconds for ecommerce triggers) and are not retried. Your endpoint must answer quickly and you should reconcile from your own records if a delivery is missed.
- Channel, ecommerce and payment webhooks are currently sent without a signature header, even though the channel Webhooks tab mentions one. Verify requests by source instead, for example with a hard-to-guess path.
- The Calls and Outgoing Messages checkboxes on channel webhooks are not forwarded today.
- Every processed workflow step counts as a task on your plan, and External API Call steps use paid tasks.
Sources
- Webhooks for the WhatsApp Business Platform — Meta for Developers, checked 12 October 2026
- Templates overview — Meta for Developers, checked 12 October 2026
Broadchat team · Product and partner success team
The people who build and support Broadchat, the white-label WhatsApp Business API platform. We write from what we see while onboarding partners and their clients on the official WhatsApp Cloud API, and we check every article against Meta's current documentation.
Last updated:
Frequently asked questions
Can I send a WhatsApp message when someone fills a form on my website?
Yes. Have the form post its data to a workflow's Custom Webhook URL, then send an approved template with Send Template Message (V2), mapping the phone number and variables from the form fields. The person must have agreed to be contacted on WhatsApp.
How do I secure a Broadchat webhook URL?
The token in the URL is the credential, so keep it out of client-side code and public repositories. If it leaks, click Re-Generate Hook; the old URL stops working immediately. Call the URL from your server, not from the visitor's browser.
Does Broadchat retry a webhook if my server is down?
No. Outbound webhooks are sent once. Make your endpoint answer quickly and reconcile from your own records, or use the channel's message statuses to detect gaps.
What format are forwarded WhatsApp messages in?
Channel webhooks forward Meta's own webhook format (object whatsapp_business_account with entry and changes), one change per request. Code written for Meta's Cloud API webhook can usually read it without changes.