Skip to main content
Webhooks let your app receive HTTP notifications when WhatsApp events happen.

​
Create a webhook

  1. Go to your WhatsApp configuration
  2. Click Manage Webhooks → Add Webhook
  3. Enter your HTTPS endpoint URL
  4. Select events you want to receive:
    • Message received: New customer messages
    • Message sent: Your messages sent to WhatsApp
    • Conversation created: New conversations
    • Conversation ended: Conversation closes
    • Message delivered: Message delivery confirmation
    • Message read: Customer read your message
    • Message failed: Message delivery failed
  5. Click Create Webhook
Copy the secret key from the webhook details. You’ll need it to verify signatures.

​
Webhook payload

Your endpoint receives POST requests with this structure: 
{
  "message": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "message_type": "text",
    "content": "Hello!",
    "direction": "inbound",
    "phone_number": "+1234567890",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "conversation": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "phone_number": "+1234567890",
    "status": "active"
  },
  "whatsapp_config": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "display_phone_number": "+15551234567"
  }
}

​
Verify signatures

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

​
Next steps

Full webhooks guide

Message buffering, inactivity timeouts, and advanced configuration.
⌘I