BizOne-portal/reference/05-webhook-spec.md

Webhook Specification

Public Endpoints

• GET /webhooks/whatsapp
• POST /webhooks/whatsapp
• POST /webhooks/whatsapp/:provider

Responsibilities

• Validate verification token or signature
• Store raw payload
• Detect duplicate event_id
• Enqueue processing job
• Return 200 quickly

Internal Normalized Event Format

{
  "provider": "meta",
  "event_type": "message.delivered",
  "event_id": "evt_123",
  "sender_phone": "628xxxx",
  "recipient_phone": "628yyyy",
  "external_message_id": "wamid.xxx",
  "timestamp": "2026-05-08T06:00:00.000Z",
  "payload": {}
}

Internal Event Types

• message.inbound
• message.sent
• message.delivered
• message.read
• message.failed
• template.updated
• account.updated

Processing Flow

1. Receive request
2. Verify authenticity
3. Save webhook_events record
4. Ignore duplicates
5. Push job to queue
6. Worker parses and updates data
7. Mark processed or failed