Each event is a POST of JSON to your URL. Every event goes to every webhook of the number (at most 5): filter by type in your receiver.
A number's webhooks get every number event. Account and partner webhooks (/v1/account/webhooks, /v1/partner/webhooks) also get the Partner events.
Envelope
{
"id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
"type": "message.received",
"created": "2026-11-06T01:00:00.000Z",
"number": "4976659348270",
"data": {
"message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
"from": "61412345678",
"name": "Sample Contact",
"type": "text",
"text": "Hi, is my order on its way?",
"conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
"timestamp": "2026-11-06T01:00:00.000Z",
"from_user_id": "AU.1234567890123456",
"whatsapp": {
"from": "61412345678",
"from_user_id": "AU.1234567890123456",
"id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
"timestamp": "1762390800",
"type": "text",
"text": {
"body": "Hi, is my order on its way?"
}
}
}
} Headers
Content-Typeapplication/json; charset=utf-8User-Agentapp2email-webhooks/1.0X-App2email-Eventthe event typeX-App2email-Deliverythe event id (evt_…), the same on every retry: drop repeats by itX-App2email-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">; a second v1= while an old secret is keptX-Hub-Signature-256sha256=<hex HMAC-SHA256 of the raw body>, as Meta signs (current secret only)X-App2email-Testtrue, on test events onlyyour headersthe webhook's custom headers, if any
Signature
Key: the webhook's signing secret (whsec_…) as it is, prefix included. Check every v1= (two during a secret change), over the raw body, and refuse an old t.
import crypto from "node:crypto";
// rawBody: the body exactly as received (Buffer or string), eg express.raw({ type: "application/json" })
export function verifyWebhook(rawBody, header, secret, toleranceSeconds = 300) {
const t = /(?:^|,)\s*t=(\d+)/.exec(header ?? "")?.[1];
const v1 = [...(header ?? "").matchAll(/(?:^|,)\s*v1=([0-9a-f]+)/g)].map((m) => m[1]); // every v1=: two while an old secret is kept
if (!t || v1.length === 0 || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
const expected = crypto.createHmac("sha256", secret).update(t + ".").update(rawBody).digest("hex");
return v1.some((v) => v.length === expected.length && crypto.timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
}
// const ok = verifyWebhook(req.body, req.get("X-App2email-Signature"), process.env.WEBHOOK_SECRET); import hashlib, hmac, re, time
def verify_webhook(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
t = re.search(r"(?:^|,)\s*t=(\d+)", header or "")
v1 = re.findall(r"(?:^|,)\s*v1=([0-9a-f]+)", header or "") # every v1=: two while an old secret is kept
if not t or not v1 or abs(time.time() - int(t.group(1))) > tolerance:
return False
expected = hmac.new(secret.encode(), t.group(1).encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(v, expected) for v in v1)
# ok = verify_webhook(request.get_data(), request.headers.get("X-App2email-Signature"), WEBHOOK_SECRET) <?php
function verify_webhook(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
if (!preg_match('/(?:^|,)\s*t=(\d+)/', $header, $t)) return false;
preg_match_all('/(?:^|,)\s*v1=([0-9a-f]+)/', $header, $m); // every v1=: two while an old secret is kept
if (!$m[1] || abs(time() - (int)$t[1]) > $tolerance) return false;
$expected = hash_hmac('sha256', $t[1] . '.' . $rawBody, $secret);
foreach ($m[1] as $v) if (hash_equals($expected, $v)) return true;
return false;
}
// $ok = verify_webhook(file_get_contents('php://input'), $_SERVER['HTTP_X_APP2EMAIL_SIGNATURE'] ?? '', getenv('WEBHOOK_SECRET')); Answer and retries
- Your URL has to answer with a 2xx status (eg 200) within 10 seconds. Redirects are not followed.
- A failed event is sent again after 10 s, 1 min, 5 min, 30 min, 1, 2, 4, 8 and 16 hours (about 32 hours in all; the planned tries survive a restart).
- After 20 events in a row not delivered within their first 4 tries (over at least 24 hours) the webhook is turned off; PATCH
{"active": true}turns it on. - Delivery log: the last 100 events per webhook, 7 days, every attempt (GET …/deliveries); send one again: POST …/redeliver.
Format and custom headers
formatper webhook:app2email(default, the envelope above) ormeta(Meta'sentry[].changes[]object as Meta sent it, signed the same way; app2email's own events keep the envelope).headersper webhook: up to 5, egAuthorization: Basic …; after saving, values show their last 4 characters only. Not allowed:Host,User-Agent,Content-*,X-App2email-*,X-Hub-*,Proxy-*,X-Forwarded-*, connection headers.- Both on POST /webhooks and PATCH /webhooks/{id}.
Events
| Type | When |
|---|---|
| Messages | |
| message.status | A message sent from the number was sent, delivered, read, failed or deleted. |
| message.received | A contact sent a message or tapped a button. While WhatsApp's AI agent holds the conversation (owner whatsapp_ai) a reply goes through only after it passes the conversation on (conversation.owner_changed). |
| message.failed | A message sent from the number failed (the same data as message.status). |
| message.edited | A contact edited a message they sent. |
| message.deleted | A contact deleted a message they sent. |
| Contacts | |
| contact.opted_out | A contact was added to the Do Not Call list by their own action. |
| contact.updated | A contact was made or changed through the API (upsert, patch, consent; not imports), or turned marketing messages back on in WhatsApp. |
| contact.changed_number | A contact changed their WhatsApp number, or their business-scoped user id changed. |
| Broadcasts | |
| broadcast.completed | A broadcast finished sending, was cancelled, or its scheduled time was missed. |
| Account | |
| usage.threshold | 80% or 100% of the billing month's messages are used (once each per month). |
| Templates | |
| template.status_changed | WhatsApp approved, rejected, paused or disabled a template, changed its quality or category, or it was edited (change components). WABA-wide: every number gets it. |
| Conversations | |
| conversation.owner_changed | Who handles a contact changed: human, agent, paused or back to normal; or WhatsApp's AI agent took or passed on the conversation (owner whatsapp_ai). |
| Approvals | |
| message.held_for_approval | A send was held by the key's approval gate. |
| approval.resolved | A held send was approved (and sent), rejected, or expired. |
| Book-and-Pay | |
| waitlist.joined | A customer joined the waitlist of a full day (on a personal booking link, confirmed on WhatsApp after the public page, in the calendar app or through the API). |
| waitlist.notified | A customer on the waitlist was offered a time that opened (WhatsApp, the waitlist template or e-mail). |
| waitlist.removed | A customer was taken off the waitlist (by themselves, the business or the API). |
| booking.created | An appointment was booked: by the customer in the WhatsApp Flow, on the dashboard, or through the API. |
| booking.cancelled | An appointment was cancelled: by the customer (CANCEL on WhatsApp), the business, the API or app2email. |
| booking.rescheduled | An appointment was moved to another time (the old one is in rescheduled_from). |
| booking.rated | The customer rated a completed appointment (the follow-up message's buttons). |
| flow.completed | A contact finished a form Flow of the Book-and-Pay section (kind form); a booking Flow sends booking.created instead. |
| booking.updated | An appointment's details changed: the customer's name or e-mail, the notes, the answers or the staff member (in the calendar app, on the dashboard or through the API). Not sent for a move (booking.rescheduled) or a cancel. |
| booking.note.created | An internal note was added to a customer or an appointment (in the calendar app or through the API). |
| calendar.block.created | Time was blocked in the calendar (in the calendar app or through the API). |
| calendar.block.deleted | A time block was removed from the calendar. |
| booking.paid | An appointment was paid online (the payment provider confirmed it, or a deposit was paid). Not sent for a payment the business recorded by hand. |
| booking.refunded | An appointment's online payment was refunded, in full or in part (from the calendar, the API, or automatically when it is cancelled). |
| payment.paid | A payment request or a package purchase was paid online. |
| package.purchased | A prepaid package was bought online (paid) or given to a customer (granted). |
| poll.voted | Someone voted (or changed their vote) on a meeting poll. |
| poll.closed | A meeting poll was closed, or its winning time was booked (status booked, with chosen_option). |
| booking.customer.erased | A customer's booking data was erased on request (DELETE /bookings/customers/{contact}, the calendar app, or the contact delete with booking_data=erase). |
| Calling | |
| call.incoming | A WhatsApp user calls the number (with their SDP offer). Answer with POST /calls within 30 to 60 s. |
| call.status | A call rang, was accepted, rejected or connected, ended, or its recording or transcript is ready. |
| Number | |
| number.updated | WhatsApp changed something about the number or its account: quality, messaging limit, throughput, display name, status, restriction, connection ... |
| number.error | WhatsApp reported an error that is not about one message, eg too many messages in a short time. |
| Flows | |
| flow.status_changed | A flow was published, throttled, blocked or deprecated, Meta raised or cleared an endpoint or client alert, or its Flow JSON version expires soon. WABA-wide: every number gets it. |
| Partner(account and partner webhooks only) | |
| client.created | A client signed up on your site, was made by POST /v1/partner/clients, or finished an onboarding link. |
| client.updated | A client's name changed, or a suspended client is active again. |
| client.suspended | A client was suspended. |
| number.created | A number was connected (Meta's Embedded Signup finished). |
| number.ready | A number went LIVE (once per number): it can send. |
| number.disconnected | WhatsApp took app2email's access away (account offboarded, partner removed, deleted). |
| number.reconnected | The number's WhatsApp account is connected again. |
| subscription.created | A client number got a plan (Stripe checkout, a free or a given plan). |
| subscription.renewed | A plan's period moved on (a renewal was paid). |
| subscription.payment_failed | A renewal could not be charged (status past_due or unpaid). |
| subscription.cancelled | A plan ended (cancelled, unpaid, replaced by another plan, or ended by you). |
| trial.ending | A number's trial ends within 3 days. |
| trial.expired | A number's trial ended without a plan. |
| plan.limit_reached | A number used all messages of its plan this billing period (once per period). |
| api_key.created | A key of a number was made (Partner API, account API or dashboard). |
| api_key.revoked | A key of a number was revoked. |
| Order-and-Pay | |
| order.created | An order became real: placed to pay later, paid online, or confirmed on WhatsApp by a visitor of the order page. Not sent while an order still waits for its payment or its confirmation. |
| order.paid | The online payment of an order was confirmed by the payment provider. payment.paid is sent as well. |
| order.accepted | The staff accepted an order by hand. An order that is accepted automatically says so in order.created (status accepted). |
| order.ready | An order was marked ready. |
| order.completed | An order was handed over at the counter or delivered. |
| order.cancelled | An order was cancelled by the customer or the staff, or declined by the staff. |
| order.refunded | A refund of an order was recorded: from the dashboard, the counter, or one made in the payment provider's own dashboard. |
| order.no_show | The staff closed a pickup order that was ready and never collected. The order's status is cancelled; order.cancelled is not sent for it. |
| Submit-Info | |
| submission.created | A submission was made: on WhatsApp, on the web page, by a team member or through the API. Its files may still be arriving (files_pending above 0): submission.files_ready follows. |
| submission.files_ready | Every file of a submission is stored, so files[].url can be fetched. Sent once, and only for a submission that has files. |
| submission.updated | Answers, internal values, the priority, the tags, the due time or the pin of a submission changed, a file was added to it by a team member or the API, or the submitter of a web submission proved their number. |
| submission.status_changed | A submission moved to another stage: a team member, the API, an automation, or the submitter pressing a button. |
| submission.assigned | The assignee of a submission changed (to a member, or to nobody). |
| submission.note_added | A team member or the API wrote an internal note on a submission. |
| submission.customer_replied | The submitter added something to a submission: text or files after Add more or on their status page, a follow-up form, or a button of a reply. |
| submission.deleted | A submission was deleted (restorable for 30 days) or erased for good. |
| submit.automation_failed | An automation gave up on a submission: an outside call still failed after its retries (1 minute, 10 minutes, 1 hour). GET /submit/runs?status=failed has every step. |
| Tickets-and-Pay | |
| ticket.order.confirmed | An order's tickets were issued: paid online, free and confirmed, complimentary, or paid outside. Once per order. page_url is empty in events: read the order with GET /tickets/orders/{id}. |
| ticket.order.refunded | Tickets of an order were refunded or cancelled: by staff, the API, a cancelled date, or a full refund made at the payment provider. Not sent for a late payment that was returned before any ticket existed. page_url is empty in events: read the order with GET /tickets/orders/{id}. |
| ticket.checked_in | A ticket was admitted for the first time (not for a re-entry, a check-out or a refused scan). page_url is empty in events: read the order with GET /tickets/orders/{id}. |
| ticket.passed_on | A holder passed a ticket on: the old ticket stopped working and a new one was made. page_url is empty in events: read the order with GET /tickets/orders/{id}. |
| ticket.event.sold_out | A date sold its last public ticket. Once per time it becomes sold out. |
| ticket.event.cancelled | A date was cancelled and its refunds have finished. Cancelling an event sends one per date. |
| ticket.waitlist.joined | Someone joined the waiting list of a sold-out date. |
| ticket.buyer.erased | A buyer's ticket data was erased on request. |