Field reference for WhatsApp account_update webhooks: WABA lifecycle events, restrictions, partner events, pricing tiers, MM API terms, offboarding, and Dualhook handling.

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

Event	What to do
`ACCOUNT_DELETED`	Treat the WABA as no longer usable.
`ACCOUNT_RESTRICTION`	Read `restriction_info` and stop affected actions until resolved or expired.
`ACCOUNT_VIOLATION` / `DISABLED_UPDATE`	Escalate account quality and policy review.
`PARTNER_APP_INSTALLED`	A customer granted app permissions. Confirm expected WABA ownership and scopes.
`PARTNER_APP_UNINSTALLED`	A customer revoked app permissions. Expect token or management failures.
`PARTNER_REMOVED`	The WABA was unshared from the partner. If `disconnection_info` is present, inspect the reason.
`ACCOUNT_OFFBOARDED`	The WABA was offboarded after device change or phone number reregistration.
`ACCOUNT_RECONNECTED`	The WABA reconnected after a device change or phone number reregistration.
`AUTH_INTL_PRICE_ELIGIBILITY_UPDATE`	Store the effective start time and exception countries.
`VOLUME_BASED_PRICING_TIER_UPDATE`	Update pricing-tier reporting for the category, region, and effective month.
`MM_LITE_TERMS_SIGNED`	The WABA accepted MM API for WhatsApp terms.

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:

Object	Used for
`waba_info`	Partner app events, partner sharing, MM API terms, ad account linking.
`violation_info`	Policy or terms violations.
`restriction_info`	Account restrictions and any remediation text.
`ban_info`	Disablement and reinstatement state.
`disconnection_info`	Coexistence disconnection reason and who initiated it.
`auth_international_rate_eligibility`	Authentication-international pricing effective dates.
`volume_tier_info`	Volume-based pricing tier, category, region, and effective month.

Dualhook Handling

Dualhook treats account_update as a high-priority management field. It is received on Dualhook's app-level callback, interpreted for connection and account state, and forwarded to your configured endpoint.

Dualhook uses these events to surface account restrictions, offboarding, reconnection, partner removal, permission revocation, pricing-tier signals, and MM API terms acceptance. For Platform API customers, related lifecycle state may also appear in signed Dualhook platform events. Dualhook stores operational metadata and delivery status only; no customer message bodies or media are part of this field.

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_APP_UNINSTALLED, PARTNER_REMOVED, ACCOUNT_OFFBOARDED, and ACCOUNT_DELETED as connection-impacting events.
PARTNER_REMOVED can include disconnection_info for WhatsApp Business app plus Cloud API setups. Reasons such as PRIMARY_INACTIVITY, COMPANION_INACTIVITY, CHANGE_NUMBER, and USER_RE_REGISTERED are operationally meaningful.
Multiple VOLUME_BASED_PRICING_TIER_UPDATE events can describe the same tier change. Use the earliest tier_update_time for canonical reporting.

account_update Webhook

What account_update Reports

Key Event Values

Payload Shape

Dualhook Handling

Implementation Notes

Related