Receive WhatsApp messages
Inbound webhooks forward supported direct WhatsApp messages and interactive replies to your application. They are not outbound delivery callbacks or SMS receipts.
Add an endpoint
Open Webhooks, choose a WhatsApp channel, and add a public HTTPS endpoint.
Each endpoint has its own label, signing secret, and enabled state. Save the generated secret when it is shown. Changing the URL or rotating the secret generates a new secret; update your receiver accordingly.
You can enable multiple endpoints for the same channel. They all receive the same supported events; labels do not filter or route messages. Private/internal addresses and redirects are blocked.
Understand the event
Ziph sends a JSON POST with event name message.received. This is an illustrative text event:
{
"version": 1,
"id": "EVENT_ID",
"event": "message.received",
"channel_id": "CHANNEL_ID",
"timestamp": "2026-11-19T10:00:00Z",
"message": {
"provider_message_id": "PROVIDER_MESSAGE_ID",
"sender": "SENDER_ADDRESS",
"conversation": "CONVERSATION_ADDRESS",
"text": "Hello"
}
} Quick-reply selections add message.button_reply; list selections add message.list_reply. Both contain id, title, and an optional quoted_provider_message_id when WhatsApp supplies it. The selected title also appears in message.text.
Treat the sender’s text and selection IDs as untrusted input. Verify the signature, validate the event, and deduplicate its ID before performing a business action. Groups, broadcasts, incoming media, and self-sent messages are not forwarded.
Verify the signature
Read these headers:
X-Ziph-Timestamp: the Unix timestamp of the delivery attempt, in seconds.X-Ziph-Signature:sha256=followed by a hexadecimal HMAC-SHA256 digest.
Compute HMAC-SHA256 using the endpoint’s signing secret. The signed bytes are the timestamp header, a literal period, and the raw HTTP body bytes, in that order. Do not parse and reserialize the body before verification.
This Node.js example takes the raw body as a Buffer and the two header values as strings:
import { createHmac, timingSafeEqual } from 'node:crypto';
function verifyWebhook(rawBody, timestamp, signature, secret) {
if (!/^\d+$/.test(timestamp ?? '')) return false;
if (!/^sha256=[0-9a-f]{64}$/.test(signature ?? '')) return false;
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = createHmac('sha256', secret)
.update(timestamp + '.')
.update(rawBody)
.digest();
const received = Buffer.from(signature.slice(7), 'hex');
return timingSafeEqual(expected, received);
} The five-minute freshness window above is a receiver policy to limit replay, not a Ziph retry guarantee. Keep the receiver’s clock synchronized and deduplicate valid event IDs as well.
Acknowledge quickly
Return a successful 2xx response after verification and any durable handoff your application requires. Keep processing within the five-second delivery timeout.
Delivery is best-effort and events can be lost. There are no retries, replay tools, or inbound message archives.
Deleting a channel also deletes its webhook configuration. A request already in flight cannot be recalled.