The WhatsApp user_id_update webhook Meta told you to subscribe to doesn't exist

Meta's July 2026 WhatsApp documentation told developers to subscribe to a user_id_update webhook field to detect BSUID changes. On 11 August 2026, Meta corrected the page. The field doesn't exist, was never subscribable, and never appeared in the App Dashboard.

If you found this after spending hours trying to locate user_id_update in the App Dashboard — you were following the docs correctly. The docs were wrong.

What is a BSUID?

A BSUID (business-scoped user ID) is a privacy layer in the WhatsApp Business Platform. Instead of exposing a user's phone number directly, WhatsApp assigns a unique identifier per business-user pair.

Format: CC.<up_to_128_chars> — for example 91.abc123xyz

Key property: BSUIDs can change without the user changing their phone number. This is why BSUID change events exist in the first place.

How BSUID changes are actually delivered

BSUID change events are delivered on your existing messages webhook subscription as a system message — not on any new field. The webhook payload looks like this:

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "type": "system",
          "system": {
            "type": "user_changed_user_id",
            "identity": "new_bsuid_value",
            "wa_id": "phone_number"
          }
        }]
      },
      "field": "messages"
    }]
  }]
}

The silent enum change you also need to know about

There's a breaking enum value change that happened silently:

• Before (July 2026 docs): user_changed_user_id meant the user's phone number changed
• After (August 2026 correction): user_changed_user_id means the user's BSUID changed (phone number unchanged)
• Current enum for phone changes: user_changed_number

If your integration was checking system.type === "user_changed_user_id" to detect phone number changes, you were using the wrong trigger even when the docs said otherwise. That logic now means BSUID change.

What you need to do

1. Audit your webhook handler — find any code checking system.type values
2. Map existing logic: rename user_changed_user_id handlers to BSUID change handlers
3. Phone number changes: use user_changed_number going forward
4. No new webhook subscription needed — BSUID change events come through your existing messages subscription as system messages
5. Delete any user_id_update subscription logic — the field does not exist, was never valid

The full breakdown

The complete technical write-up — including the exact payload format, enum reference table, migration checklist, and what Meta's correction actually says — is on the BotSense blog:

WhatsApp BSUID webhook: the user_id_update field that doesn't exist

If you hit this while building a WhatsApp integration, drop a comment — curious how many teams were blocked by this.