Does account_update tell me when my messaging limit changes?

No. Limit changes arrive in the business_capability_update webhook, and denied limit increases in account_alerts. account_update covers enforcement, partner links, deletion and pricing-tier events.

Which account_update event fires when a business finishes Embedded Signup?

PARTNER_ADDED, whose waba_info gives the new WABA ID and the owner's business ID. PARTNER_APP_INSTALLED follows when the business grants your app permissions. Subscribing the WABA to your app is still a separate call.

How do I know when a restriction ends?

Each restriction_info item has an expiration timestamp. Schedule a check for that time, confirm in WhatsApp Manager, and resume sending deliberately rather than assuming the restriction lifted.

What should I do when an ACCOUNT_RESTRICTION event arrives?

Pause exactly what the restriction blocks and alert a named owner. Store each restriction_type with its expiration, stop business-initiated campaigns if RESTRICTED_BIZ_INITIATED_MESSAGING is listed, keep the inbox open for customers who write in, and read any remediation text before appealing in WhatsApp Manager.

WhatsApp account_update Webhook: Events & Payloads

Description

What is the account update webhook?

The account update webhook is account_update, one of the webhook fields of the WhatsApp Business Platform. Where the messages field reports what happens to individual messages, account_update reports what happens to the WhatsApp Business Account (WABA) itself: a policy violation, an account restriction on what it may do, a WhatsApp account ban being scheduled or lifted, the account being shared with or removed from a partner, its deletion, or a move between tiers under volume tier pricing.

Every notification names what happened in value.event, and the rest of value depends on that event. Enforcement events carry violation_info.violation_type (ACCOUNT_VIOLATION), a restriction_info array of restriction_type, expiration and optional remediation (ACCOUNT_RESTRICTION), or ban_info with waba_ban_state set to SCHEDULE_FOR_DISABLE, DISABLE or REINSTATE (DISABLED_UPDATE). Partner events (PARTNER_ADDED, PARTNER_APP_INSTALLED, PARTNER_APP_UNINSTALLED, PARTNER_REMOVED) carry a waba_info object, PARTNER_CLIENT_CERTIFICATION_STATUS_UPDATE reports a partner-led business verification decision, and VOLUME_BASED_PRICING_TIER_UPDATE carries volume_tier_info.

It is easy to confuse with its neighbours. The phone number quality webhook concerns one business number, the business capability update webhook (business_capability_update) reports the portfolio's messaging limit, and account_alerts covers limit-increase denials, Official Business Account decisions and lost profile photos. account_update is the account's legal and commercial status. It always goes to the app's default callback URL, because Meta does not let account-level webhooks follow a WABA or phone number override.

Key takeaways

The account update webhook (account_update) reports changes to a whole WhatsApp Business Account, not to one message or one number.
Route on value.event: violations, restrictions, ban states, partner links and pricing-tier changes each carry their own object.
On partner events such as PARTNER_ADDED, read the WABA ID from waba_info.waba_id, not from entry.id.
Since 1 October 2025, a change of volume pricing tier also arrives here as VOLUME_BASED_PRICING_TIER_UPDATE.
Account-level events go to the app's default callback URL, so keep that endpoint live even if messages use an override.

Properties

The account update webhook: key facts and limits

Webhook field: account_update
Scope: One WhatsApp Business Account
Discriminator: value.event (16 documented values, more added over time)
Ban states: SCHEDULE_FOR_DISABLE, DISABLE, REINSTATE
Volume tier changes: Reported here since 1 October 2025
Callback override: Not supported: always the app's default URL
Retries on failure: Decreasing frequency, up to 7 days

Usage

The account update webhook in code

1// account_update always arrives on the app's default callback URL.
2export async function onAccountUpdate(entry, change) {
3  const v = change.value;
4  switch (v.event) {
5    case "PARTNER_ADDED":
6      // Read the WABA from waba_info: entry.id is not the customer's WABA here.
7      await onboarding.subscribe(v.waba_info.waba_id);
8      break;
9    case "ACCOUNT_RESTRICTION":
10      for (const r of v.restriction_info ?? []) {
11        await compliance.restrict(entry.id, r.restriction_type, r.expiration, r.remediation);
12        if (r.restriction_type === "RESTRICTED_BIZ_INITIATED_MESSAGING") {
13          await campaigns.pauseAll(entry.id);
14        }
15      }
16      break;
17    case "ACCOUNT_VIOLATION":
18      await compliance.alert(entry.id, v.violation_info?.violation_type);
19      break;
20    case "DISABLED_UPDATE":
21      await compliance.banState(entry.id, v.ban_info.waba_ban_state, v.ban_info.waba_ban_date);
22      break;
23    case "VOLUME_BASED_PRICING_TIER_UPDATE":
24      await billing.recordTier(entry.id, v.volume_tier_info);
25      break;
26    default:
27      await audit.log("account_update", entry.id, v.event, v); // new events appear over time
28  }
29}

Branch on the event, read the WABA ID from waba_info on partner events, and log anything unknown.

Mechanics

How does the account update webhook work?

step 1 — Subscribe the app to the field
Tick account_update in the app's webhook fields, and make sure each WABA is subscribed to the app through subscribed_apps. The events then reach the app's default callback URL, whatever overrides are set.
step 2 — Route on value.event
Branch on the event string, not on which fields happen to be present. Keep a default branch that logs unknown events: Meta has added new ones over time, such as the volume tier event in October 2025.
step 3 — Take the WABA ID from the right place
On enforcement events entry.id is the WABA. On partner events Meta says waba_info identifies the account, and in its examples entry.id differs from waba_info.waba_id, so never treat it as the customer's WABA.
step 4 — Act on enforcement
For ACCOUNT_RESTRICTION, store each restriction_type with its expiration and pause exactly what it blocks: RESTRICTED_BIZ_INITIATED_MESSAGING stops business-initiated sends while customer-initiated chats may still work, and other types restrict adding phone numbers, utility templates or calling.
step 5 — Close the loop
Alert a named compliance owner, show the state in your admin screens and record REINSTATE or the restriction's expiry so sending resumes deliberately rather than by accident.

Caveats

Common mistakes with the account update webhook

Taking entry.id as the WABA on partner events
On PARTNER_ADDED and the other partner events, entry.id in Meta's examples is not the customer's WABA ID. Subscribing or storing that ID as the account breaks onboarding; always read waba_info.waba_id.
Only listening to messages
Teams that subscribe to messages alone learn about restrictions from failing sends. Subscribe to account_update from day one and route enforcement events to a person, not just a log.
A switch with no default
New event values arrive without warning. A handler that throws on an unknown event returns an error, Meta retries for days, and the endpoint fills with duplicates. Log unknown events and return 200.
Expecting it on the override URL
WABA and phone number overrides move message traffic only. Account-level events still go to the app's default callback URL, so that endpoint must stay live even if all messaging moved elsewhere.

Example

Example: One clinic restricted, 119 untouched

A Coimbatore software firm sends appointment reminders for 120 clinics, each on its own WABA. One morning its endpoint receives account_update with event: ACCOUNT_RESTRICTION and RESTRICTED_BIZ_INITIATED_MESSAGING for one clinic's account. The handler pauses only that clinic's reminder queue, keeps its inbox open for patients who write in, and emails the account manager the expiration date and remediation text. The other 119 clinics carry on, and the firm avoids a morning of failed sends.

Why it matters

Why does the account update webhook matter?

A restriction or a scheduled ban is the most expensive event a WhatsApp integration can miss. If nobody reads account_update, campaigns keep firing into a restricted account, every send fails, and the first anyone hears of it is a customer complaint. For a partner serving many businesses it is also the onboarding signal — the event that hands over a new customer's WABA ID — and the billing signal when a volume tier changes.

Notes

Best practices for the account update webhook

Store the full payload of every enforcement event; it is the evidence you need for an appeal.
Show a restriction banner, with its expiry, in the same screen where users launch campaigns.
Treat PARTNER_REMOVED and PARTNER_APP_UNINSTALLED as offboarding: stop sending and revoke stored tokens. On coexistence numbers, PARTNER_REMOVED adds disconnection_info with a reason such as PRIMARY_INACTIVITY.
Feed VOLUME_BASED_PRICING_TIER_UPDATE into billing reconciliation rather than reading tiers by hand.

Questions

Account Update Webhook FAQs

Does account_update tell me when my messaging limit changes?: No. Limit changes arrive in the business_capability_update webhook, and denied limit increases in account_alerts. account_update covers enforcement, partner links, deletion and pricing-tier events.
Which account_update event fires when a business finishes Embedded Signup?: PARTNER_ADDED, whose waba_info gives the new WABA ID and the owner's business ID. PARTNER_APP_INSTALLED follows when the business grants your app permissions. Subscribing the WABA to your app is still a separate call.
How do I know when a restriction ends?: Each restriction_info item has an expiration timestamp. Schedule a check for that time, confirm in WhatsApp Manager, and resume sending deliberately rather than assuming the restriction lifted.
What should I do when an ACCOUNT_RESTRICTION event arrives?: Pause exactly what the restriction blocks and alert a named owner. Store each restriction_type with its expiration, stop business-initiated campaigns if RESTRICTED_BIZ_INITIATED_MESSAGING is listed, keep the inbox open for customers who write in, and read any remediation text before appealing in WhatsApp Manager.

See InfiQ pricing

Account Update Webhook

Follow one WABA's life through account_update

What is the account update webhook?

The account update webhook: key facts and limits

The account update webhook in code

How does the account update webhook work?

Common mistakes with the account update webhook

Taking entry.id as the WABA on partner events

Only listening to messages

A switch with no default

Expecting it on the override URL

Example: One clinic restricted, 119 untouched

Why does the account update webhook matter?

Best practices for the account update webhook

Account Update Webhook FAQs

See how this works on InfiQ

Put Account Update Webhook to work

See how this works on InfiQ