account_update Webhook

The account_update field is the broad WABA lifecycle webhook. It covers partner sharing, permission grants and revocations, policy violations, offboarding, reconnection, pricing-tier changes, MM API terms, and business-location updates.

What account_update Reports

Use this field for account-level changes that affect whether a WABA can stay connected, send messages, use specific features, or remain shared with a provider.

It can report:

• WABA deletion, restriction, violation, disablement, or reinstatement,
• partner app install, uninstall, added, or removed events,
• device-change or phone-number-reregistration offboarding and reconnection,
• authentication-international rate eligibility,
• primary business location country changes,
• MM API for WhatsApp terms acceptance,
• volume-based pricing tier changes,
• partner-led business verification status changes.

Key Event Values

Events Missing from Meta's Reference

Meta's reference does not list these events, but Dualhook receives them on account_update. Their meaning is not documented by Meta, so treat them as informational.

These events use event_time (a string) inside value, and actor.business_name can name another business, such as a partner whose app changed its subscription.

Payload Shape

The wrapper is stable; the nested object changes by event.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "time": 1743451903,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
              {
                "restriction_type": "RESTRICTED_BIZ_INITIATED_MESSAGING",
                "expiration": 1743451903
              }
            ]
          }
        }
      ]
    }
  ]
}

Useful nested objects:

Events about a single business phone number, such as ACCOUNT_VIOLATION and ACCOUNT_RESTRICTION events for calling, also include phone_number with the display phone number.

Documented restriction_info[].restriction_type values:

remediation is included only when Meta has remediation steps to offer.

Dualhook Handling

Dualhook subscription: subscribed, mostly forwarded. Dualhook's Meta app subscribes to account_update. Meta does not allow Webhook Override for account-level fields, so every event arrives on Dualhook's app-level callback.

Dualhook treats account_update as a high-priority management field. It interprets each event for connection and account state and forwards it to your configured endpoint, with one exception: partner lifecycle events (PARTNER_ADDED, PARTNER_REMOVED, PARTNER_APP_INSTALLED, PARTNER_APP_UNINSTALLED, PARTNER_CLIENT_CERTIFICATION_STATUS_UPDATE), MM_LITE_TERMS_SIGNED, and ACCOUNT_DELETED concern the partner relationship between your WABA and Dualhook. Dualhook consumes those itself and does not forward them. The undocumented events listed above are forwarded like any other.

Dualhook uses these events to surface account restrictions, offboarding, reconnection, partner removal, permission revocation, pricing-tier signals, and MM API terms acceptance. Dualhook stores operational metadata and delivery status only; no customer message bodies or media are part of this field.

The routing effect depends on the event:

• PARTNER_REMOVED, PARTNER_APP_UNINSTALLED, and ACCOUNT_DELETED terminally remove only connection rows on the affected customer WABA. Other WABAs in the same organization are untouched.
• A terminal partner event is applied only when it includes the affected WABA and a valid entry.time, and only when that event is not older than the connection's current authorization. Malformed or stale deliveries are retained for investigation but do not delete anything.
• ACCOUNT_OFFBOARDED places a reversible hold. ACCOUNT_RECONNECTED releases it only after Meta access and webhook routing are validated.
• A disablement or scheduled disablement places a durable account hold. Reinstatement releases it only after validation.
• A customer-initiated messaging restriction, alone or together with a business-initiated one, blocks the connection until Meta's supplied expiry. A business-initiated restriction on its own (RESTRICTED_BIZ_INITIATED_MESSAGING) keeps the connection and its webhook routing active: until the expiry, the Runtime API refuses template sends with business_initiated_restricted and still relays replies inside an open customer service window. Calling, phone-add, and template-only restrictions remain alerts for the affected operation rather than full connection blocks.
• Partner-added and app-installed events are onboarding evidence only. They never reactivate an existing connection by themselves.

Implementation Notes

• Switch on value.event first, then parse the nested object for that event.
• Keep unknown event values. Meta adds new account events over time.
• Treat partner removal/deletion as WABA-scoped terminal events and offboarding/reconnection as reversible routing events.
• PARTNER_REMOVED can include disconnection_info for WhatsApp Business app plus Cloud API setups. Inspect the reason before choosing a recovery path.

Documented disconnection_info.reason values:

• Multiple VOLUME_BASED_PRICING_TIER_UPDATE events can describe the same tier change. Use the earliest tier_update_time for canonical reporting.

Related

• Webhook Subscription Fields
• Webhook Events & Notifications
• Maintain Account Health
• WhatsApp Policy Enforcement
• Pricing
• MM API Onboarding