Contact created
Incoming webhook deliveries are authenticated with HMAC signature headers (X-Chatway-Signature and X-Chatway-Timestamp), not your Chatway API key.
A new contact was added or identified.
Use contact.created to create or link a contact in your CRM. Store data.contact.id as the Chatway identifier so later Contact updated events can update the same record. Use this ID with Get Chat Contact to retrieve the profile. Choose Conversation created instead when your workflow starts with a new chat, such as opening a support ticket.
For signature verification and retries, see Webhooks overview.
POST webhook: contact.createdParameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
X-Chatway-Event | header | Yes | string | Event name for this delivery. Example: contact.created |
X-Chatway-Webhook-Id | header | Yes | string (uuid) | Unique webhook subscription ID. Example: 9f3c2a1b-4d5e-4f70-8a9b-0c1d2e3f4a5b |
X-Chatway-Delivery-Id | header | Yes | string | Unique ID for this HTTP delivery attempt (`del_` + 32 hex characters). A new value is sent on each retry. Example: del_1b0279b1f28f12c0b9f2a2fdbf3758ee |
X-Chatway-Delivery-Attempt | header | Yes | string | Attempt number for this event (`1` on first try). Sent as a decimal string in the header. Example: 1 |
X-Chatway-Timestamp | header | Yes | string | Unix timestamp in seconds when the request was signed. Sent as a decimal string in the header. Example: 1770201001 |
X-Chatway-Signature | header | Yes | string | `sha256=` followed by the lowercase hex HMAC SHA256 of `{X-Chatway-Timestamp}.{raw request body}`, keyed with your webhook secret. The example is computed for the example body serialized as compact JSON, the example timestamp, and the placeholder secret `whsec_exampleSecretForDocsOnly00000000`. Example: sha256=cc4aa06d573d14318f0fc5d240d22a7ec9609ae342d64dc6f9f615a6063cb011 |
Request body
Signed JSON envelope for this event.
application/json
id (string, required)— Stable event ID (`evt_…`). Same across HTTP retries for this notification.event (string, required)— Event name. For this webhook, always `contact.created`.data (object, required)— Payload for contact.created.contact (object, required)id (string (uuid), required)name (string|null, required)— Contact name. Always present; null when unknown.email (string|null, required)— Contact email. Always present; null when unknown.phone (string|null, required)— Contact phone. Always present; null when unknown.source (string, required)— Page URL or normalized channel label.created_at (string (date-time))
conversation (object)— The contact's latest conversation. Omitted when the contact has no conversation yet.id (string (uuid), required)— Conversation ID.channel (string, required)— Normalized channel.status (string, required)— Conversation status.widget_name (string)— Present when the conversation is tied to a website widget.identifier (string)— Widget identifier when widget_name is present.
occurred_at (string (date-time), required)— When the business event occurred.version (string, required)— Payload schema version.
Responses
200
Return any 2xx status to acknowledge receipt.
410
Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. Like every non-2xx response below 500 (including 408 and 429), it is not retried. It does not disable the subscription; turn the webhook off in Chatway Settings if you want deliveries to stop.
Examples
Request body example
{
"id": "evt_1234567890abcdef1234567890abcdef",
"event": "contact.created",
"data": {
"contact": {
"id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
"name": "John Doe",
"email": "[email protected]",
"phone": "+1XXXXXXXXXX",
"source": "https://example.com/pricing",
"created_at": "2026-02-04T10:30:00Z"
},
"conversation": {
"id": "0f46c0a1-8938-40e3-b2b5-bb56f569fcab",
"channel": "website",
"status": "open",
"widget_name": "Main site widget",
"identifier": "eouqtiupanm6uvglwshy"
}
},
"occurred_at": "2026-02-04T10:30:00Z",
"version": "2026-09"
}