Webhook Events & Notifications

Management webhook events: template status, quality updates, account alerts, and forwarding.

Delivery Model

Dualhook configures webhook subscriptions and override at the WABA level, then routes traffic as follows:

Message-path events (messages, history, smb_message_echoes) are delivered directly from Meta to your webhook endpoint.
Management events are received on the app-level callback for operational handling, then forwarded to your configured webhook endpoint.

Dualhook does not proxy or store message bodies or media. Dualhook stores and processes operational metadata for monitoring and dashboards.

Managed Event Fields

Dualhook tracks these management fields:

message_template_status_update
message_template_quality_update
phone_number_quality_update
phone_number_name_update
account_update
account_review_update
business_capability_update
smb_app_state_sync
template_category_update
security
account_alerts
history

Message-Path vs Management Events

Field	Delivery path	Dualhook behavior
`messages`	Meta → your endpoint (override)	Not ingested for content processing
`smb_message_echoes`	Meta → your endpoint (override)	Not ingested for content processing
`history`	Meta → your endpoint (override)	If seen on app callback, treated as routing anomaly and logged
Management fields	App callback → Dualhook → your endpoint	Metadata handled for state updates + forwarded

Template Status Update

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "message_template_status_update",
          "value": {
            "message_template_id": "123456789012345",
            "message_template_name": "order_update_v1",
            "message_template_language": "en_US",
            "event": "APPROVED"
          }
        }
      ]
    }
  ]
}

Template Category Reclassification

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "template_category_update",
          "value": {
            "message_template_id": "123456789012345",
            "message_template_name": "promo_like_utility",
            "old_category": "UTILITY",
            "new_category": "MARKETING"
          }
        }
      ]
    }
  ]
}

Phone Number Quality Update

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "event": "QUALITY_UPDATED",
            "phone_number_id": "123456789012345",
            "display_phone_number": "15550001234",
            "current_limit": "TIER_10K",
            "current_quality_rating": "YELLOW",
            "previous_quality_rating": "GREEN"
          }
        }
      ]
    }
  ]
}

Account Alert

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "changes": [
        {
          "field": "account_alerts",
          "value": {
            "alert_type": "POLICY_ENFORCEMENT",
            "alert_severity": "HIGH",
            "alert_description": "Recent activity may violate messaging policy."
          }
        }
      ]
    }
  ]
}

Forwarding Headers

When Dualhook forwards management events to your endpoint, it adds:

X-Dualhook-Event
X-Dualhook-WABA
X-Dualhook-Connection
X-Dualhook-Trace

Reliability Behavior

Event forwarding timeout: 15 seconds.
Delivery status is logged (delivered, failed, pending).
Duplicate management events within a short window are deduplicated using event metadata.