Webhooks
A webhook tells your server when something happens in EzReach. EzReach sends a signed JSON request to an address you choose, and sends it again if your server does not answer.
Set up an endpoint
- Build a page on your server that accepts a
POSTwith a JSON body and answers200quickly. It must be reachable on the internet overhttps. - In EzReach, open Settings > Developers > Webhooks and choose Add endpoint. Only owners and admins can do this.
- Enter the address, an optional description, and pick the events you want. You can change them later.
- Copy the signing secret. It starts with
whsec_and is shown once. Keep it on your server. You will use it to check every request. - Choose Send test event. EzReach sends a
webhook.testrequest right away and shows you what your server answered.
What your address must be
httpsonly, at most 2,048 characters, with nouser:password@and no#fragment.- A public address on the internet. EzReach refuses
localhost, names ending in.local,.internal,.lanor.corp, names without a dot, and any name that points to a private, loopback or reserved network address. It checks when you save the endpoint and again on every request. - Answer with
2xxwithin 10 seconds. Do slow work after you have answered. A3xxcounts as a failure: EzReach never follows redirects. - While you build, expose your laptop with a tunnel that gives you an
httpsaddress, and use Send test event.
What a request looks like
Every request body is one JSON object:
POST to your address
{
"id": "evt_5f1c9a0b2d3e4f5061728394",
"type": "message.status",
"created_at": "2026-10-19T10:15:03.120Z",
"data": {}
}| Field | Meaning |
|---|---|
id | The event id (evt_ and 24 letters or digits). It is also sent in the EzReach-Event-Id header. A retry and "Resend" send the same id and the same body: use it to ignore an event you have already handled. Each endpoint gets its own copy with its own id. |
type | One of the event names on the events page. Also sent in the EzReach-Event-Type header. |
created_at | When EzReach recorded the event (ISO 8601, UTC). The time the thing itself happened is inside data. |
data | The details of the event. Every event page shows one example. |
- Field names are snake_case. Enum values are lower-case snake_case (
delivered,no_messages,in_appeal). - Times are ISO 8601 in UTC. Phone numbers are E.164 (
+919876543210). - A field with nothing to say is
null. It is never missing. - Events can arrive out of order and, rarely, more than once. Order them by the times inside
data, and ignore anidyou have already handled. - A body is at most 64 KB. Message text is cut at 4,096 characters.
Headers
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | EzReach-Webhooks/1 |
EzReach-Event-Id | The event id (evt_...), the same as id in the body. |
EzReach-Event-Type | The event type, the same as type in the body. |
EzReach-Signature | t=<unix seconds>,v1=<hex HMAC-SHA256>. See Signatures. |
The events
13 events. See each one with an example.
| Event | When it is sent |
|---|---|
message.received | Someone sent you a WhatsApp message. |
message.status | A WhatsApp message you sent was sent, delivered, read or failed. |
contact.opted_out | Someone stopped offers or all WhatsApp messages (STOP, WhatsApp settings, your team or the API). |
contact.opted_in | Someone can get more WhatsApp messages again (START, a sign-up, your team or the API). |
template.status_updated | Meta approved, rejected, paused or disabled one of your templates. |
email.delivered | An email reached the person's mailbox. |
email.bounced | An email bounced (the address is wrong, or the mailbox could not take it). |
email.complained | Someone marked your email as spam. |
email.opened | Someone opened a campaign email (when open tracking is on; machine opens are left out). |
email.clicked | Someone clicked a link in a campaign email (when click tracking is on). |
email.unsubscribed | An email address was unsubscribed (the unsubscribe link, a spam report, your team or the API). |
rsvp.submitted | Someone completed your RSVP form in WhatsApp. |
campaign.completed | A WhatsApp or email campaign finished sending. |

