Webhooks Guide
Configure webhook endpoints to receive real-time WhatsApp events.
Webhooks deliver real-time events from your WhatsApp sessions to your application endpoints. Instead of polling APIs, your server receives instant HTTP POST notifications when something happens.
Supported event types include message.received, message.sent, message.delivered, message.read, message.failed, media.uploaded, session.connected, session.disconnected, and automation.triggered.
To configure a webhook, go to Settings > Webhooks in your dashboard, add your endpoint URL, and select which event types to receive. WAStack sends signed POST requests to your endpoint with JSON payloads.
Every webhook includes an X-WAStack-Signature header with an HMAC-SHA256 signature. Verify this signature using your webhook secret to ensure the request came from WAStack.
Failed deliveries are retried with exponential backoff: 1 minute, 5 minutes, 15 minutes, 1 hour, 6 hours, 24 hours. After 6 failed attempts, the webhook is paused and you're notified.
Event Types
Receive events for messages (received, sent, delivered, read, failed), media uploads, session status changes, and automation triggers.
Payload Structure
Each webhook includes event type, timestamp, session ID, and event-specific data. Payloads are consistent JSON with predictable schemas.
Signature Verification
Verify the X-WAStack-Signature header using HMAC-SHA256 with your webhook secret. This ensures webhook authenticity.
Retry Logic
Failed webhooks are retried with exponential backoff (1m, 5m, 15m, 1h, 6h, 24h). After 6 failures, the webhook is paused.
Code Examples
import crypto from "crypto";
export async function POST(req) {
const body = await req.text();
const signature = req.headers.get("x-wastack-signature");
const secret = process.env.WEBHOOK_SECRET;
const expected = crypto
.createHmac("sha256", secret)
.update(body)
.digest("hex");
if (signature !== `sha256=${expected}`) {
return new Response("Invalid signature", { status: 401 });
}
const event = JSON.parse(body);
// Process event...
return new Response("OK", { status: 200 });
}Ready to implement?
Start building with WAStack APIs. Connect your WhatsApp in under 5 minutes.
Start FreeFrequently asked questions
Common questions about webhooks guide.
Browse all documentation
From getting started to advanced API patterns, find everything you need to build WhatsApp automation.