Technical reference

Webhooks: inbound events to your HTTPS endpoint

Page updated: 2026-04-03

Summary

WAPing POSTs JSON events to your HTTPS URL when messages arrive, delivery states change, or session health changes. Payload shapes are defined on docs.waping.app— they are not identical to Meta’s Cloud API webhook format.

Canonical reference: Hostnames, path prefixes, JSON field names, and changelog are maintained on docs.waping.app. Examples below are illustrative — align your integration with the live OpenAPI/reference there.

Connection model: WAPing links WhatsApp through a QR session (similar in concept to WhatsApp Web). This is not Meta’s WhatsApp Business Cloud API product, and you do not complete Meta BSP / Cloud API onboarding inside WAPing for this path.

Key definitions

Term	Definition
Webhook URL	Your HTTPS endpoint that WAPing POSTs to; must be reachable from WAPing infrastructure.
Verification handshake	One-time or periodic challenge to prove URL ownership—exact mechanism is in the canonical docs.
At-least-once delivery	Your handler may see duplicates or retries; dedupe on event id (or equivalent) in the payload.

Purpose

Replace polling with push notifications for automation, sync, and observability.

Best for

Automation that reacts to inbound messages, delivery updates, or session health within seconds.
Queues or workers that ack fast and process asynchronously.

Not for

Copy-pasting Meta Cloud API webhook parsers without adapting fields—payload shapes differ.
Long synchronous work inside the HTTP handler (risk timeouts and duplicate retries).

WAPing vs Meta Cloud API webhooks (contrast)

Aspect	WAPing	Meta Cloud API (contrast)
Sender	WAPing platform to your URL	Meta to your URL (per their app config)
Payload	WAPing event JSON per docs.waping.app	Meta's documented webhook fields
Interchangeable?	No — adapters or separate code paths are required if you support both models.

Workflow

Register a publicly reachable HTTPS URL in the dashboard (developer settings).
Complete the verification handshake (challenge/token) when the product requires it — exact parameters are in the canonical reference.
Return 2xx quickly; enqueue work to a worker queue.
Process events idempotently using a stable eventId (or equivalent) from the payload.

Request example (delivery to your server)

POST /your/webhook

POST /your/webhook HTTP/1.1
Host: api.customer.com
Content-Type: application/json
X-Wap-Signature: {signature_if_configured{'}'}

{
  "eventId": "evt_123",
  "type": "message.received",
  "timestamp": "2026-04-03T12:00:00Z",
  "deviceId": "dev_123",
  "message": {
    "id": "msg_in_456",
    "from": "+15559876543",
    "body": "Hi — where is my order?"
  }
}

Response example (your handler)

Ack quickly

HTTP/1.1 200 OK
Content-Type: application/json

{ "received": true }

Errors (from your endpoint’s perspective)

If you return non-2xx or time out, WAPing records a failed delivery and applies retry policy — see Retries. Do not rely on a single delivery attempt.

Retries

Failed deliveries are retried with exponential backoff over a bounded window. Your handler must be idempotent — the same logical event may be retried or duplicated on edge cases; dedupe on eventId.

Plan and throughput

Webhooks are included only on tiers that include developer access; throughput is also bounded by fair-use and abuse-prevention rules. Return 2xx quickly and buffer bursts in your own queue.

Plan	WhatsApp devices (linked)	Outbound messages / month	REST API & webhooks
Free	1	500	Not included
Starter	1	3,000	Included
Growth	5	30,000	Included
Pro	15	300,000	Included
Enterprise	50	1,000,000	Included

REST API + webhooks column reflects published plans (2026-04-03).

Security

Validate a signature or shared secret when the product provides one (see canonical docs for header names and algorithms).
Use TLS 1.2+ on your endpoint; pin expectations if you operate strict ingress.
Treat payloads as untrusted JSON — validate schema before side effects.

Caveats

WAPing does not guarantee exactly-once delivery at your HTTP layer — design for at-least-once with idempotent consumers.
Session events may arrive before or after related API calls — order by timestamp and IDs.