contact.updated

Sent with the contact as it is after the change, and what changed. Use it to keep your own contact records current. A new WhatsApp profile name alone sends nothing.

Called Contact updated in the app. Part of the plan feature webhooks.contacts. To subscribe over the API, the key needs contacts:read.

PayloadPOST to your endpoint

{
  "id": "evt_d5954c993ce66ff8242f457b7134a172",
  "type": "contact.updated",
  "api_version": "2026-10-14",
  "created_at": "2026-10-14T10:05:27.947Z",
  "workspace_id": "2b7e4c1a-9d3f-4a85-b6e2-5f0c8d1a7e34",
  "data": {
    "contact": {
      "id": "4ea0d485-435d-407f-837a-c7d67095f23a",
      "phone": "+919876543210",
      "whatsapp_user_id": null,
      "name": "Priya Sharma",
      "whatsapp_name": "Priya S",
      "attributes": {
        "customer_id": "8812",
        "city": "Mumbai",
        "orders": 4
      },
      "tags": [
        "VIP"
      ],
      "marketing_opt_out": false,
      "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
      "chat": {
        "status": "open",
        "assigned_agent_id": "5b1d7d0e-3c2a-4f61-9a0e-6f8f3b2c1d40",
        "last_message_at": "2026-10-14T09:30:12.481Z",
        "last_inbound_at": "2026-10-14T09:12:40.117Z"
      },
      "created_at": "2026-10-14T09:05:11.420Z",
      "updated_at": "2026-10-14T10:05:27.733Z"
    },
    "changed": [
      "attributes"
    ]
  }
}

Headers

webhook-id: The delivery’s ID, the same on every try.
webhook-timestamp: When this try was sent, in Unix seconds.
webhook-signature: v1, and an HMAC-SHA256 of the request.

How delivery and retries work

Data

What’s in data. Every event wraps it in the same envelope.

contact object

The contact as it is after the change.

Show 12 child attributesHide child attributes

contact.id string · uuid

contact.phone string · nullable

The number as + and its digits. null for a contact known only by a WhatsApp username.

contact.whatsapp_user_id string · nullable

The ID WhatsApp gives a contact who uses a WhatsApp username. null if WhatsApp hasn’t given Soosh one.

contact.name string · nullable

The name your business gave the contact, in the app or through the API. null if nobody has. A new WhatsApp profile name never replaces it.

contact.whatsapp_name string · nullable

The contact’s own WhatsApp profile name.

contact.attributes object

Your own fields on the contact. Names are 1 to 64 letters, digits or underscores.

A map; each value is a string or number or boolean.

contact.tags array of strings

contact.marketing_opt_out boolean

Whether the contact opted out of marketing messages.

contact.number_id string · uuid · nullable

The WhatsApp number the contact is usually messaged from.

contact.chat object

The contact’s chat. last_inbound_at covers any number. The 24-hour window is per number, so don’t work it out from this field.

Show 4 child attributesHide child attributes

contact.chat.status string

One of open closed.

contact.chat.assigned_agent_id string · uuid · nullable

contact.chat.last_message_at string · date-time · nullable

contact.chat.last_inbound_at string · date-time · nullable

contact.created_at string · date-time

contact.updated_at string · date-time

changed array of strings

The fields that changed. More values may be added.

Any of name attributes tags number_id marketing_opt_out. At least 1 item.

Handling it

Answer with any 2xx within 10 seconds. Do the work after.
Check the signature first. Verify webhooks has the code.
Subscribe with POST /v1/webhooks, events: ["contact.updated"].