Browse the docs

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

  1. Build a page on your server that accepts a POST with a JSON body and answers 200 quickly. It must be reachable on the internet over https.
  2. In EzReach, open Settings > Developers > Webhooks and choose Add endpoint. Only owners and admins can do this.
  3. Enter the address, an optional description, and pick the events you want. You can change them later.
  4. 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.
  5. Choose Send test event. EzReach sends a webhook.test request right away and shows you what your server answered.

What your address must be

  • https only, at most 2,048 characters, with no user:password@ and no #fragment.
  • A public address on the internet. EzReach refuses localhost, names ending in .local, .internal, .lan or .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 2xx within 10 seconds. Do slow work after you have answered. A 3xx counts as a failure: EzReach never follows redirects.
  • While you build, expose your laptop with a tunnel that gives you an https address, 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": {}
}
FieldMeaning
idThe 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.
typeOne of the event names on the events page. Also sent in the EzReach-Event-Type header.
created_atWhen EzReach recorded the event (ISO 8601, UTC). The time the thing itself happened is inside data.
dataThe 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 an id you have already handled.
  • A body is at most 64 KB. Message text is cut at 4,096 characters.

Headers

HeaderValue
Content-Typeapplication/json
User-AgentEzReach-Webhooks/1
EzReach-Event-IdThe event id (evt_...), the same as id in the body.
EzReach-Event-TypeThe event type, the same as type in the body.
EzReach-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256>. See Signatures.

The events

13 events. See each one with an example.

EventWhen it is sent
message.receivedSomeone sent you a WhatsApp message.
message.statusA WhatsApp message you sent was sent, delivered, read or failed.
contact.opted_outSomeone stopped offers or all WhatsApp messages (STOP, WhatsApp settings, your team or the API).
contact.opted_inSomeone can get more WhatsApp messages again (START, a sign-up, your team or the API).
template.status_updatedMeta approved, rejected, paused or disabled one of your templates.
email.deliveredAn email reached the person's mailbox.
email.bouncedAn email bounced (the address is wrong, or the mailbox could not take it).
email.complainedSomeone marked your email as spam.
email.openedSomeone opened a campaign email (when open tracking is on; machine opens are left out).
email.clickedSomeone clicked a link in a campaign email (when click tracking is on).
email.unsubscribedAn email address was unsubscribed (the unsubscribe link, a spam report, your team or the API).
rsvp.submittedSomeone completed your RSVP form in WhatsApp.
campaign.completedA WhatsApp or email campaign finished sending.