Webhooks
Send GTM Clarity events to your own systems in real time, as signed JSON POSTs to your HTTPS endpoint.
Configure
In the console, open Integrations and add an endpoint under Outbound webhooks, choosing the agent it is for. An endpoint added there receives every event for that agent.
To receive only some events, register the endpoint with the API, using a write key, and list them in events:
curl https://app.gtmclarity.ai/api/v1/customers/42/webhook-endpoints \
-X POST \
-H 'Authorization: Bearer gtmc_your_key_here' \
-H 'Content-Type: application/json' \
-d '{
"url": "https://example.com/webhooks/gtmclarity",
"events": ["conversation.started", "conversion.recorded"]
}'
Omit events or send null to receive all events; an empty list receives none. The response includes a whsec_... signing secret, shown once. Store it immediately. To manage endpoints, see their delivery attempts or rotate the secret through the API, see Events & webhooks.
Payload
{
"event": "conversation.started",
"data": {
"customerId": 42,
"orgId": "org_2h9x4kQ",
"conversationId": 118,
"visitorId": "6f9d2c1e-8a3b-4f70-9c55-2d41e0b7a9c3"
},
"ts": 1784448000
}
Fields are camelCase. customerId, conversationId, conversionEventId, resolutionEventId and escalationId are integers; orgId, visitorId and resolvedPersonId are strings. ts is the Unix time the delivery was sent, not when the event happened: the immediate retry repeats it, later retries carry a new one.
Events
customerId and orgId are always present in data.
| Event | Additional data keys |
|---|---|
conversation.started | conversationId, visitorId (may be null) |
conversation.ended | conversationId, status, converted |
identity.resolved | conversationId, source, and whichever of resolvedPersonId, name, email, company, title are known (unknown keys are omitted) |
conversion.recorded | conversionEventId, conversationId, conversionType, value (the conversion's details as a JSON-encoded string, or null when an operator recorded the lead) |
resolution.recorded | resolutionEventId, conversationId, resolvedPersonId (may be null), resolvedCompany (may be null) |
handoff.requested | escalationId, conversationId, waitingSince (when this wait began), schemaName, urgency, reason (may be null) |
outcome.marked | conversationId, category - the outcome category recorded for the chat, or null when it was cleared |
conversion.recorded and conversation.ended also carry qualifiers, an array of { id, label, type, value }, when the visitor answered any qualifying questions.
The captured lead
conversion.recorded, conversation.ended and handoff.requested also carry lead: the contact details captured on the chat, as the visitor typed them or an operator entered them. It is the same object as a conversation's lead in the API, and the same details the lead email shows.
"lead": {
"name": "Ada Lovelace",
"firstName": null,
"lastName": null,
"email": "ada@example.com",
"phone": "+61400000000",
"company": null,
"callbackRequested": true,
"preferredContactTime": "after 5pm",
"chatStartedOn": "https://example.com/sell"
}
| Field | Notes |
|---|---|
name, firstName, lastName, email, company | null when not captured |
phone | In international (E.164) format, or null when not captured or not a valid number |
callbackRequested | true when the visitor asked to be phoned back |
preferredContactTime | When to contact them, in the visitor's own words, or null |
chatStartedOn | The page the chat started on: its address without the query string |
lead is always present on these three events. It is null when the chat could not be read or has been erased. A lead captured after an event was sent is not in that event: read the conversation from the API for the latest.
handoff.requested fires when a chat starts waiting for a person, and may fire once more when the visitor leaves contact details while it waits. Both carry the same escalationId and waitingSince: treat them as one request and keep the latest lead. A visitor who comes back to the same chat later starts a new wait: same escalationId, new waitingSince.
identity.resolved is also sent when a prospect with an email is re-synced by hand to a connected CRM, with a different shape and no conversationId: prospectKey, email, and whichever of name, company, rung are known, plus historical: false.
The delivery timeout is 5 seconds. Respond with a 2xx quickly and do the work asynchronously. A delivery that fails or times out is retried once at once, then again after at least 5 minutes, 30 minutes and 2 hours (retries are sent every 15 minutes, so each can be up to 15 minutes later). After the fifth attempt it is not sent again.
So a delivery can arrive more than once, and events can arrive out of order. Payloads carry no delivery id and no event time. conversionEventId, resolutionEventId and escalationId identify their events. The other events have no unique key, and conversation.ended and outcome.marked can legitimately fire more than once for the same chat.
Verify signatures
Each request carries two headers:
X-GTMC-Signature: t=<ts>,v1=<hex>X-GTMC-Timestamp: <ts>
v1 is the hex HMAC-SHA256 of the string <ts>.<raw request body>: the timestamp, a full stop, then the body exactly as received. The key is the whole whsec_... secret as text: do not strip the prefix or base64-decode it. Compute it over the raw body before parsing the JSON, compare in constant time, and reject a request when |now - t| is over your tolerance (300 seconds is recommended).
TypeScript:
import { Buffer } from 'node:buffer';
import crypto from 'node:crypto';
export function verifyGtmcSignature(secret: string, header: string, rawBody: string, toleranceSeconds = 300): boolean {
const parts = new Map(header.split(',').map((part) => {
const [key, ...rest] = part.split('=');
return [key, rest.join('=')];
}));
const timestamp = Number(parts.get('t'));
const signature = parts.get('v1');
if (!Number.isInteger(timestamp) || !signature) {
return false;
}
if (Math.abs(Math.floor(Date.now() / 1000) - timestamp) > toleranceSeconds) {
return false;
}
const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
const actual = Buffer.from(signature, 'hex');
const wanted = Buffer.from(expected, 'hex');
return actual.length === wanted.length && crypto.timingSafeEqual(actual, wanted);
}
Python:
import hashlib
import hmac
import time
# raw_body: the request body as bytes, e.g. Flask request.get_data() or Django request.body.
def verify_gtmc_signature(secret, header, raw_body, tolerance_seconds=300):
parts = dict(part.partition("=")[::2] for part in header.split(","))
try:
timestamp = int(parts.get("t", ""))
except ValueError:
return False
signature = parts.get("v1")
if not signature or abs(int(time.time()) - timestamp) > tolerance_seconds:
return False
expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature.encode(), expected.encode())