Real-time events
Integrate WhatsApp with Webhook
A webhook is the simplest server-to-server integration mechanism: instead of your system constantly asking whether something new has arrived, it receives an HTTP POST request at the exact moment an event happens. You expose a public URL (an endpoint on your backend) and the provider delivers the event payload to it. It is the pattern used by practically every modern platform to notify about received messages, delivery status changes, payment updates and the like, with no polling and very low latency.
Why connect
Connecting ZapZap API to your own webhook handles both sides of WhatsApp cleanly: incoming messages are pushed to your server and outgoing messages go out via REST. Picture an e-commerce store that wants to reply right away when a customer sends "where is my order" on WhatsApp. Without a webhook, your system would have to poll the API in a loop, wasting latency and processing. With a webhook, ZapZap API fires a POST to your endpoint the instant the message arrives, your backend looks up the order in the database and replies by calling ZapZap API's sending endpoint, all within seconds. Since the number runs on a managed instance with community warm-up and an anti-ban layer, you lower the risk of the account going down while keeping full control of the flow in your code. Each active number costs R$15 per month, prepaid, and you start with a welcome credit when you create the account, subject to the current campaign. Test the integration before scaling.
Step by step
- 1
Create the endpoint that will receive the events
On your backend, expose a public route that accepts POST, for example POST https://yoursystem.com/webhooks/zapzap. It must read the JSON body of the request and respond quickly with a 2xx status (200 or 204). Responding outside the 2xx range makes the event be treated as a failure and resent. If you do not have a public URL in your development environment yet, start a tunnel with ngrok (ngrok http 3000) and use the generated https URL.
- 2
Make the endpoint reachable and idempotent
Make sure the URL responds over HTTPS and that no authentication blocks the provider's POST (or allow the webhook's IP/route). Treat the payload as potentially duplicated: store the event or message ID and ignore redeliveries you have already processed. That way, if the same event arrives twice because of a retry, you do not reply to the customer twice.
- 3
Register the webhook URL on your ZapZap API instance
In the ZapZap API dashboard, open the WhatsApp instance and go to the Webhook section. Paste your endpoint URL and select the events you want to receive, such as incoming message and delivery status. Save. From then on, every event from that instance will be delivered to your endpoint. The exact event names and the payload format are in the docs at https://api.zapzapapi.com/llms.txt.
- 4
Process the event and fire the reply via REST
When the POST arrives, extract the sender's number and the message text from the body. Run your logic (look up an order, trigger an AI, write to the CRM) and reply by calling ZapZap API's sending endpoint with the x-api-key and x-api-secret headers. Always return 2xx on the webhook even if the heavy processing continues in the background, so you do not block the delivery queue.
- 5
Test end to end in production
Send a real message to the instance's number and confirm in your server logs that the POST arrived with the expected payload. Then check that the automatic reply went out on WhatsApp. Monitor the webhook delivery logs in the dashboard: non-2xx deliveries are recorded for diagnosis, so that is where you investigate whether your endpoint rejected any event.
Example
// Your endpoint receives the event (Express)
app.post('/webhooks/zapzap', (req, res) => {
res.sendStatus(200); // respond 2xx first
const { numero, texto } = req.body; // ILLUSTRATIVE fields, see docs
// your logic here, then reply through WhatsApp:
});
// Send a reply via REST (exact fields in the docs)
fetch('https://api.zapzapapi.com/api/v1/{instanceId}/send/text', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'x-api-secret': 'YOUR_API_SECRET',
'Content-Type': 'application/json'
},
body: JSON.stringify({ numero: '5511999999999', texto: 'Received!' })
});
// Exact structure of routes and fields: https://api.zapzapapi.com/llms.txtIllustrative. The exact fields and endpoints are in the documentation.
Frequently asked questions
Do I need my own server to use a webhook?
Yes, a webhook requires a public URL that accepts POST. It can be your own backend (Node, PHP, Python), a serverless function or a flow in tools like n8n and Make. In development, you can use a tunnel such as ngrok to expose localhost.
What is the difference between receiving by webhook and sending by REST?
They are the two directions of the conversation. The webhook is ZapZap API pushing events to your system (incoming message, delivery status). REST is your system calling ZapZap API to send messages. You use both together to build automatic replies.
What happens if my endpoint is down when an event arrives?
If your endpoint does not respond with a 2xx status, the delivery is recorded as a failure. That is why it pays to respond 2xx quickly and process the rest in the background, and to treat the payload as possibly duplicated so you can handle redeliveries without processing the same event twice.
How much does it cost and how does authentication work?
Each active number costs R$15 per month, prepaid, and you start with a welcome credit when you create the account, subject to the current campaign. Receiving by webhook is configured in the instance dashboard. The REST sending calls use the x-api-key and x-api-secret headers, generated in your account.
Where do I find the exact event names and payload fields?
In the documentation at https://api.zapzapapi.com/llms.txt. The examples in this guide are illustrative to show the flow; the real event names, routes and fields live in the docs, which are the official source.
Start now
Create your account, connect a number in minutes and test the API with warm-up and anti-ban. R$15 per active number/month, prepaid, no lock-in.