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. 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.
Business-initiated and customer-initiated messaging restrictions block the connection until Meta's supplied expiry. 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:

Reason	Meaning
`ACCOUNT_DISCONNECTED`	The account was disconnected due to enforcement, or the client explicitly deleted their WhatsApp account.
`BUSINESS_DOWNGRADE`	The client registered the business phone number with the consumer WhatsApp app.
`CHANGE_NUMBER`	The client changed their phone number.
`COMPANION_INACTIVITY`	A companion device was inactive for approximately 30 days.
`PRIMARY_INACTIVITY`	The primary device was inactive for approximately 14 days.
`USER_RE_REGISTERED`	The client re-registered on a new device.

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