Webhooks Overview & Quickstart

When an event occurs on your connected WhatsApp devices (inbound message, status delivery tick, device disconnect, or QR stream), the Wahide engine immediately processes the event through a resilient, event-driven pipeline: 1. **Zero-Heap Event Filtering**: Unnecessary noisy events (groups, stories, channel newsletters) are filtered out to protect your server from overload. 2. **Standardized JSON Envelope**: The event data, device identifier, sender details, and timestamps are packaged into a structured schema. 3. **Asynchronous HTTP POST Delivery**: Wahide dispatches an HTTP POST request to the webhook URL configured in your dashboard. 4. **Instant Acknowledgment**: Your server acknowledges receipt by returning an HTTP `200 OK` response within 8 seconds.

To verify that incoming requests genuinely originate from Wahide and protect your endpoint from spoofing or replay attacks, Wahide includes standard HTTP authentication headers on every request:

POST /api/webhook/whatsapp HTTP/1.1
Host: api.your-business.com
Content-Type: application/json
User-Agent: Wahide-WhatsApp-Webhook-Engine/2.0
X-Wahide-Secret: whsec_live_9f8e7d6c5b4a3210fedcba9876543210
X-Wahide-Delivery-ID: 01JPLAN0000000000000000099
X-Wahide-Event: message.received
X-Wahide-Device-ID: 01JPLAN0000000000000000001
X-Wahide-Timestamp: 1725845000

Wahide employs an enterprise-grade delivery resilience pipeline to ensure zero dropped messages: - **Circuit Breaker Protection**: If a destination endpoint experiences 5 consecutive failures (timeout or 5xx error), the circuit trips to **OPEN** state for 30 seconds. Outbound requests are immediately dropped with HTTP 503 without holding connection sockets or worker threads. - **Jittered Exponential Backoff**: Retries are attempted up to **5 times** with increasing intervals (3s, 6s, 12s, 24s, 48s plus random jitter to prevent thundering-herd issues). - **Dead Letter Queue (DLQ)**: If all 5 attempts fail, the failed event is preserved in the in-memory DLQ with strict per-tenant bounds (up to 200 items), allowing inspection and manual replay.

Wahide allows you to subscribe strictly to events your application needs, eliminating unnecessary server load. Click on any event below to view its dedicated payload schema, parameter table, and language code examples: - [⚡ Event: message.received](/docs/webhooks/events/message-received) (*Default ON*): Inbound 1-on-1 customer messages, including direct streaming of photos and PDF documents from Cloudflare R2. - [⚡ Event: message.ack](/docs/webhooks/events/message-ack) (*Optional*): Real-time delivery receipt checkmarks (Sent to server, Delivered double-check, Read blue tick). - [⚡ Event: message.sent](/docs/webhooks/events/message-sent) (*Optional*): Outbound dispatch confirmation from device to WhatsApp network. - [⚡ Event: device.status](/docs/webhooks/events/device-status) (*Default ON*): Device connection lifecycle updates (ONLINE, OFFLINE, HIBERNATED, LOGGED_OUT). - [⚡ Event: device.qr](/docs/webhooks/events/device-qr) (*Optional*): Live streaming Base64 QR code frames for custom web pairing interfaces.

Wahide provides a flexible **2-Tier Hierarchical Routing** architecture designed to support both centralized automation platforms (such as n8n, Make, and Zapier) and complex multi-department enterprise setups: ### 1. The Two Webhook Tiers Explained - **Tenant Webhook (Default / Workspace Level)**: - Configured at **Dashboard Settings (`/settings`) → Webhook Integration**. - Authenticated with `X-Wahide-Secret: whsec_live_<32 hex>`. - Acts as the central mailbox: **All WhatsApp devices in your workspace automatically route here by default**. - **Device Webhook (Specific Hardware Override)**: - Configured at **Device Details (`/devices`) → Override Webhook**. - Authenticated with `X-Wahide-Secret: whsec_dev_<32 hex>`. - When set, incoming traffic for that specific phone number bypasses the tenant webhook and routes directly to a dedicated system (e.g. Accounting ERP, Freshdesk, or CRM). ### 2. How Wahide Selects Where to Deliver Events ``` [Incoming WhatsApp Message on Device A] │ ▼ Does Device A have a custom Webhook URL set? │ ┌──────────┴──────────┐ ▼ (YES) ▼ (NO / Empty) [Route to Device URL] [Route to Workspace Default URL] (Secret: whsec_dev_...) (Secret: whsec_live_...) ``` ### 3. Which Webhook Should You Use? | Business Use-Case | Recommended Webhook | Rationale | |---|---|---| | **n8n / Make / AI Chatbot** | **Tenant Webhook (`/settings`)** | Wahide includes `device_id` inside the JSON payload. A single n8n workflow can handle all devices and route dynamically using Switch or IF nodes. | | **Single Backend API** | **Tenant Webhook (`/settings`)** | Zero maintenance: adding new WhatsApp devices requires no webhook reconfiguration. | | **Multi-Department Enterprise** | **Device Webhook (`/devices`)** | When Customer Support uses n8n, but the Finance team requires payment receipts delivered to an internal on-premise ERP. | ### 4. Granular Event Inheritance If you specify a custom Webhook URL on a device but leave its subscribed events empty, the device automatically inherits the workspace event whitelist. If you check specific events on the device, only those selected events will be delivered to that device's URL.

Customer photos (JPEG, PNG, WebP) and PDF documents (up to 1 MB) are automatically decrypted in-memory and streamed directly to Cloudflare R2 object storage: - **$0 Egress Bandwidth**: Direct downloads via Cloudflare global edge CDN at zero bandwidth cost. - **Pre-Download Inspection**: Files larger than 1 MB or unsupported types (video, voice notes) are safely dropped before consuming gateway bandwidth, delivering a `media_error` diagnostic code. - **Auto-Purge Lifecycle**: Media objects reside under the `tmp/` prefix and are automatically deleted after 7 days.

Select your backend language below to view a production-ready webhook receiver boilerplate featuring header verification, text handling, media attachment downloading, and instant HTTP 200 OK acknowledgments.

curl -X POST "http://localhost:3000/api/webhook/whatsapp" \
  -H "Content-Type: application/json" \
  -H "X-Wahide-Secret: whsec_live_9f8e7d6c5b4a3210fedcba9876543210" \
  -d '{
    "event": "message.received",
    "device_id": "01JPLAN0000000000000000001",
    "timestamp": 1725845000,
    "data": {
      "message_id": "3EB0A1B2C3D4E5F6",
      "sender": "6281234567890",
      "sender_jid": "6281234567890@s.whatsapp.net",
      "push_name": "John Doe",
      "text": "Please check the attached payment receipt",
      "has_media": true,
      "media": {
        "type": "image",
        "url": "https://pub-r2.wahide.com/tmp/whatsapp-media/01JPLAN000/2026/09/01JPLANXYZ123456.jpg",
        "file_name": "payment_receipt.jpg",
        "mime_type": "image/jpeg",
        "file_size": 245120
      },
      "timestamp": 1725844998
    }
  }'