Webhook Events & Notifications

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.

Starting March 31, 2026, message webhooks include new BSUID fields (user_id, from_user_id) and some existing fields (wa_id, from) may be omitted. See the BSUID transition guide 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
• smb_app_state_sync
• template_category_update
• security
• account_alerts

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.