phone_number_quality_update Webhook

The phone_number_quality_update field reports changes to a business phone number's throughput level and to the messaging limit of the business portfolio that owns it. Despite its name, Meta's current reference does not put the phone number's quality rating (GREEN, YELLOW, RED) in this payload.

What phone_number_quality_update Reports

The payload identifies the phone number by its display number and carries:

• an event describing the change,
• the portfolio's messaging limit in max_daily_conversations_per_business,
• the deprecated current_limit and, for messaging-limit changes, old_limit.

Documented event values:

Earlier versions of Meta's reference also listed messaging-limit events such as UPGRADE, DOWNGRADE, FLAGGED, and UNFLAGGED. Keep unknown event values instead of rejecting them.

When It Fires

Meta sends it when a business phone number's throughput level changes, and when the owning business portfolio's messaging limit changes.

Payload Shape

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "time": 1748454394,
      "changes": [
        {
          "field": "phone_number_quality_update",
          "value": {
            "display_phone_number": "15550783881",
            "event": "THROUGHPUT_UPGRADE",
            "current_limit": "TIER_UNLIMITED",
            "max_daily_conversations_per_business": "TIER_2K"
          }
        }
      ]
    }
  ]
}

Tier Values

The limit fields use the same tier values:

Messaging limits apply to the whole business portfolio, so a change reported on one number applies to every number in that portfolio. See Capacity, Quality & Messaging Limits.

Dualhook Handling

Dualhook subscription: subscribed and forwarded. Dualhook's Meta app subscribes to phone_number_quality_update. Meta does not allow Webhook Override for this field, so it arrives on Dualhook's app-level callback and Dualhook forwards it to your endpoint with X-Dualhook-* headers.

In practice Meta has sent no phone_number_quality_update deliveries to any Dualhook connection from late July to late October 2026. Messaging-limit changes arrive as business_capability_update instead, so do not wait on this field. If one arrives, Dualhook records it in the connection's webhook log. Because the payload has no quality rating, the Health Report reads that from the phone number instead. The payload contains account metadata only, never message content.

Implementation Notes

• Match the event to a connection by display_phone_number and the WABA ID in entry[].id, since there is no phone number ID.
• Read max_daily_conversations_per_business for the limit, and fall back to current_limit only for older payloads.
• For the quality rating, read quality_rating from GET /<PHONE_NUMBER_ID> through the Runtime API, and keep that reconciliation read to at most once every five minutes.
• Pair this field with business_capability_update and account_alerts for capacity monitoring.

Related

• Webhook Subscription Fields
• Webhook Events & Notifications
• Capacity, Quality & Messaging Limits
• Messaging Health Status
• business_capability_update webhook