contact.created

Sent for every new contact, however it came in: a message, the app, the API, an import, a broadcast or the WhatsApp Business app. Use it to keep your own contact records in sync. data is the Contact.

Called Contact created 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_b62f56f0eff4d5e7fee62e866666198d",
  "type": "contact.created",
  "api_version": "2026-10-14",
  "created_at": "2026-10-14T09:05:11.634Z",
  "workspace_id": "2b7e4c1a-9d3f-4a85-b6e2-5f0c8d1a7e34",
  "data": {
    "id": "4ea0d485-435d-407f-837a-c7d67095f23a",
    "phone": "+919876543210",
    "whatsapp_user_id": null,
    "name": "Priya Sharma",
    "whatsapp_name": null,
    "attributes": {
      "customer_id": "8812",
      "city": "Pune",
      "orders": 3
    },
    "tags": [
      "VIP"
    ],
    "marketing_opt_out": false,
    "number_id": null,
    "chat": {
      "status": "open",
      "assigned_agent_id": null,
      "last_message_at": null,
      "last_inbound_at": null
    },
    "created_at": "2026-10-14T09:05:11.420Z",
    "updated_at": "2026-10-14T09:05:11.420Z"
  }
}

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.

id string · uuid

phone string · nullable

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

whatsapp_user_id string · nullable

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

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.

whatsapp_name string · nullable

The contact’s own WhatsApp profile name.

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.

tags array of strings

marketing_opt_out boolean

Whether the contact opted out of marketing messages.

number_id string · uuid · nullable

The WhatsApp number the contact is usually messaged from.

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

chat.status string

One of open closed.

chat.assigned_agent_id string · uuid · nullable

chat.last_message_at string · date-time · nullable

chat.last_inbound_at string · date-time · nullable

created_at string · date-time

updated_at string · date-time

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.created"].