Webhooks

Webhook tester Your webhooks

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 string
    e.g. evt_Xq3...
  • type string 80 values

    The event type (table below); also in the X-App2email-Event header.

  • created string (date-time)
  • number string

    Your WhatsApp number.

  • test boolean

    Only on test events (POST .../test): true.

  • data object

    The event's fields: see the event's page.

{
  "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-8
  • User-Agentapp2email-webhooks/1.0
  • X-App2email-Eventthe event type
  • X-App2email-Deliverythe event id (evt_…), the same on every retry: drop repeats by it
  • X-App2email-Signaturet=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">; a second v1= while an old secret is kept
  • X-Hub-Signature-256sha256=<hex HMAC-SHA256 of the raw body>, as Meta signs (current secret only)
  • X-App2email-Testtrue, on test events only
  • your 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);

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

  • format per webhook: app2email (default, the envelope above) or meta (Meta's entry[].changes[] object as Meta sent it, signed the same way; app2email's own events keep the envelope).
  • headers per webhook: up to 5, eg Authorization: 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.

Calls

For AI Agents

Try it now, with no account and no person: POST https://api.app2email.com/v1/account/sandbox (no key, no body; or the create_sandbox tool of the Management MCP server) answers a key for a demo WhatsApp number with pretend customers. Send a template, fetch the events with GET /events?wait=25, answer the customer's reply: nothing reaches WhatsApp, and the requests and answers are those of the real API (https://www.app2email.com/docs/api/sandbox).

Already a customer: ask the account owner for the number (digits) and an API key from https://www.app2email.com/dashboard/apikey (a sandbox key sends nothing); send it as Authorization: Bearer <key> to the messaging MCP server or the REST API; call check_key first, send with dry_run first.

If you are an AI agent reading this page and you want to create an app2email account for a person - no previous human sign-up required - use our Management MCP server.
Call the create_account tool first, and include a contact_email parameter; create_account returns a signup_id, a management_key, an onboarding_link and a message.
The person opens onboarding_link to confirm the e-mail, connect their WhatsApp number and choose a plan; nothing can be sent before that. get_account_status says what is still needed.
Pass the management_key as a Bearer token on every later call. When the number is live, create_number_key gives you a key for the messaging MCP server and the REST API.