INBOUND EVENTS & SIGNED CALLBACKS

WhatsApp API webhooks for message and session events

RelayWA can deliver webhook callbacks for events associated with its QR-linked WhatsApp sessions. Validate each event before updating a customer record, triggering an order workflow or changing the state of your application.

Register a secure HTTPS endpoint

Configure a webhook endpoint in your authorized workspace and store its signing secret in server-only configuration. Receive callbacks using a backend route that accepts the exact original request body.

Webhook configuration and event reference →

Verify the raw-body HMAC signature

RelayWA uses an HMAC-SHA256 signature over the timestamp, a period and the raw request body. Compare the digest with x-relaywa-signature using constant-time comparison; reject stale timestamps. Do not parse and reserialize the JSON before hashing it.

Tested Node.js verification example →

Deduplicate incoming event IDs

Persist the received event ID with a unique database constraint. If an event arrives more than once, acknowledge the duplicate without applying the business operation twice. Queue work only after your database transaction succeeds.

Laravel order notification and event handling →

Handle retries and uncertain outcomes

Webhook delivery retries and outbound message retries are different concerns. Your application must handle delivery failures, response timeouts and unknown send outcomes without inventing a new client message ID on every retry. Check the current API reference for supported status and retry behavior.

Direct sends and application-owned retries →

Webhook integration questions

How do I know a callback really came from my webhook integration?

Use the secret configured for that webhook to validate the timestamped HMAC signature of the exact raw HTTP body. Check timestamp freshness and compare digests in constant time.

Can a webhook be delivered more than once?

Design your receiver to be idempotent. Use unique event IDs, persist receipt, and avoid processing the same business operation twice even if a sender or network retries.

Does a successful send API response mean the message was read?

No. Request acceptance, dispatch and recipient delivery or reading are distinct states. Consult the message status and documented callback types; none is a guarantee of read receipt.

Does RelayWA send messages on a built-in retry queue?

Not in the documented integration release. Outbound scheduling, pacing and retries belong in your application; webhook callback delivery has separate behavior.

RelayWA uses unofficial QR-linked WhatsApp Web sessions, not Meta's official Cloud API. Handle consent and opt-outs, avoid unsolicited messaging, and do not assume uninterrupted service or guaranteed delivery.

Set up a QR-linked session · Canonical webhook specification · Compare connection models