WhatsApp contact identity changed event
A WhatsApp user changed phone number or Meta regenerated their business-scoped user id (BSUID).
When it fires
Fires when Meta reports the user under a new phone number (reason: "user_changed_number") or a new BSUID (user_changed_user_id, user_identity_changed or user_id_update).
Payload notes
previous and current carry the phone number, BSUID, parent BSUID and username. Use them to re-key records stored against the old value.
Already applied
Zernio has already moved the inbox conversation and the contact when the event arrives. conversationId and contactId point at them, or are null when there was none.
Delivery
Delivery is at-least-once; dedupe on the event id.
Payload
Example payload
{
"id": "7f1c2d4e-0000-4000-8000-000000000001",
"event": "whatsapp.contact.identity_changed",
"account": {
"accountId": "6a0000000000000000000001",
"profileId": "6a0000000000000000000002",
"platform": "whatsapp",
"username": "+15550001111",
"displayName": "Acme"
},
"reason": "user_changed_number",
"previous": {
"phoneNumber": "18325355831",
"businessScopedUserId": "US.13491208655302741918",
"parentBusinessScopedUserId": null,
"whatsappUsername": null
},
"current": {
"phoneNumber": "15129984441",
"businessScopedUserId": "US.13491208655302741918",
"parentBusinessScopedUserId": null,
"whatsappUsername": null
},
"contactId": "6a0000000000000000000003",
"conversationId": "6a0000000000000000000004",
"changedAt": "2026-09-30T12:00:00.000Z",
"timestamp": "2026-09-30T12:00:01.000Z"
}Response
Webhook received successfully
Changes
Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.