Webhook Events & Notifications

Delivery Model

Dualhook configures webhook subscriptions and override at the WABA level, then Meta chooses the callback target for each webhook field:

• Override-capable fields such as messages, history, smb_message_echoes, and smb_app_state_sync are delivered directly from Meta to your webhook endpoint when override is active.
• Non-overridable management fields are received on Dualhook's app-level callback for operational handling, then forwarded to your configured webhook endpoint where applicable.

With an active override, the override-capable payloads are not sent to Dualhook. Dualhook does not proxy or store message bodies, media, history, or smb_app_state_sync contact payloads. Dualhook stores and processes operational metadata for monitoring and dashboards.

For Coexistence onboarding, Dualhook triggers Meta's one-time history and smb_app_state_sync sync requests after the override is accepted. Meta then delivers any resulting payloads directly to your endpoint. A successful trigger means Meta accepted the request, not that history was shared or delivered.

With Meta's early April 2026 BSUID rollout and later username launch, message webhooks include new BSUID fields (user_id, from_user_id) and some existing fields (wa_id, from) may be omitted. See the BSUID webhook changes reference for the full list of field changes.

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
• template_category_update
• security
• account_alerts

smb_app_state_sync is not a Dualhook-managed event. In a standard Dualhook setup for WhatsApp Coexistence, Meta routes it directly to your endpoint via Webhook Override.

Message-Path vs Management Events

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 Update Events

The account_update field carries several pricing- and location-related sub-events. They share the same wrapper but differ in the event value and inner shape.

Volume-Based Pricing Tier Update

Sent when the portfolio reaches a new volume tier for a given market–category. Available since October 1, 2025.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1743451903,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "VOLUME_BASED_PRICING_TIER_UPDATE",
            "volume_tier_info": {
              "tier_update_time": 1743451903,
              "pricing_category": "UTILITY",
              "tier": "25000001:50000000",
              "effective_month": "2025-11",
              "region": "India"
            }
          }
        }
      ]
    }
  ]
}

Multiple webhooks can describe the same tier switch. Treat the one with the smallest tier_update_time as canonical.

Authentication-International Eligibility Update

Sent when the business is deemed eligible for authentication-international rates, with at least 30 days notice before billing starts.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1732057507,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "AUTH_INTL_PRICE_ELIGIBILITY_UPDATE",
            "auth_international_rate_eligibility": {
              "start_time": 1734649507,
              "exception_countries": [
                { "country_code": "ID", "start_time": 1742450707 }
              ]
            }
          }
        }
      ]
    }
  ]
}

Primary Business Location Update

Sent when Meta sets or updates the business's primary location (used to determine whether authentication-international rates apply).

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "102290129340398",
      "time": 1732057507,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "BUSINESS_PRIMARY_LOCATION_COUNTRY_UPDATE",
            "country": "BE"
          }
        }
      ]
    }
  ]
}

country is an ISO 3166-1 alpha-2 country code.

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.