Receiving incoming messages with webhooks

What incoming webhooks are

Incoming-message webhooks let Zapini notify your system, in real time, whenever a new message arrives at your WhatsApp instance. Instead of repeatedly polling the API, Zapini makes a POST request to the URL you register.

Step 1 — Create a public endpoint

Create an HTTPS endpoint on your server that accepts POST requests with a JSON body. It should respond quickly with HTTP 200 to acknowledge receipt. Do any heavy processing asynchronously so you don't delay the response.

💡 Tip: always use HTTPS for the webhook endpoint and validate the request origin before trusting the content.

Step 2 — Register the webhook URL

Provide your endpoint URL in the instance settings. From then on, every received message triggers a call to your webhook.

Step 3 — Handle the payload

The body sent to your endpoint includes data about the received message, such as the sender, content and identifiers. A simplified example:

{
  "event": "message.received",
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "from": "+5511999999999",
    "sender_name": "Maria",
    "type": "text",
    "message": "Hi, I'd like more information",
    "received_at": "2026-06-13T10:30:00Z"
  }
}

On your server, read the JSON, store the message and trigger whatever logic you need (open a ticket, update a CRM, call the API to reply, and so on).

Step 4 — Test and validate

Send a real message to the instance number and confirm your endpoint received the call. Check your server logs and make sure you are responding with HTTP 200.

Best practices

1. Respond fast (200) and process in the background.
2. Handle receipt idempotently, using the message identifier to avoid duplicates.
3. Implement retries and monitor failures on your endpoint.
4. To send automatic replies, combine the webhook with the API's send-message endpoint.