Skip to main content

Events & webhooks

Read the conversion ledger, and manage the webhook endpoints that receive events as they happen. For the events themselves (payloads, retries and signature verification), see Webhooks.

The API is read only for conversions: there is no endpoint to send or record an event.

Request examples omit the Authorization: Bearer gtmc_... header for brevity; every request needs it.

Conversions​

The conversion object​

{
"id": 5120,
"conversationId": 118,
"customerId": 42,
"type": "booked_meeting",
"value": "{\"input\":{},\"definitionVersion\":3,\"criteriaMet\":[]}",
"billedAt": "2026-10-14T15:20:12.000Z",
"billedCents": 12500,
"reversedAt": null,
"createdAt": "2026-10-14T15:20:11.000Z"
}
FieldTypeNotes
idintegerLedger event id
conversationIdinteger
customerIdinteger
typestringbooked_meeting, qualified_lead, sale, resolved_ticket, custom, captured_contact or qualified_meeting
valuestring or nullDetails recorded with the conversion. Conversions the assistant records carry a JSON-encoded string; other sources can store plain text
billedAtdate-time or nullnull when not billed
billedCentsinteger or null
reversedAtdate-time or nullSet when the charge was reversed
createdAtdate-time

List conversions​

GET /api/v1/conversions?customer_id=42&type=booked_meeting&created_after=2026-10-01T00:00:00Z HTTP/1.1
Host: app.gtmclarity.ai
ParameterTypeNotes
limitinteger1 to 100, default 20
starting_afterintegerA conversion id
customer_idintegerOnly this customer
created_afterdate-timeOnly events created after this time
billedtrue or falseWhether billedAt is set
typestringOne of the conversion types above

Returns { "data": [conversion, ...], "has_more": false }, newest first. A customer-scoped key only ever sees its own customer; asking it for another customer_id returns an empty list. Responses: 200, 400, 401, 403, 429.

Retrieve a conversion​

GET /api/v1/conversions/5120 HTTP/1.1
Host: app.gtmclarity.ai

Returns the conversion object. Responses: 200, 401, 403, 404, 429.

Webhook endpoints​

Endpoints belong to one customer. You can also add them in the dashboard; see Webhooks.

The webhook endpoint object​

{
"id": 9,
"customerId": 42,
"url": "https://example.com/webhooks/gtmclarity",
"description": "CRM bridge",
"events": ["conversation.started", "conversion.recorded"],
"active": true,
"createdAt": "2026-10-14T15:00:00.000Z"
}
FieldTypeNotes
idinteger
customerIdinteger
urlstringHTTPS URL
descriptionstring or null
eventsarray of strings or nullnull means every event. Values: conversation.started, conversation.ended, identity.resolved, conversion.recorded, resolution.recorded, handoff.requested, outcome.marked
activebooleanInactive endpoints receive nothing
createdAtdate-time

List webhook endpoints​

GET /api/v1/customers/42/webhook-endpoints HTTP/1.1
Host: app.gtmclarity.ai

Returns { "data": [endpoint, ...] }, every endpoint for the customer, newest first. Not paginated. Responses: 200, 401, 403, 404, 429.

Create a webhook endpoint​

POST /api/v1/customers/42/webhook-endpoints HTTP/1.1
Host: app.gtmclarity.ai
Content-Type: application/json

{
"url": "https://example.com/webhooks/gtmclarity",
"description": "CRM bridge",
"events": ["conversation.started", "conversion.recorded"]
}
FieldTypeNotes
urlstringRequired. Must be https and resolve to a public address
descriptionstring or null1 to 500 characters
eventsarray of strings or nullOmit or send null for every event; an empty array receives none
{
"endpoint": {
"id": 9,
"customerId": 42,
"url": "https://example.com/webhooks/gtmclarity",
"description": "CRM bridge",
"events": ["conversation.started", "conversion.recorded"],
"active": true,
"createdAt": "2026-10-14T15:00:00.000Z"
},
"secret": "whsec_Jk3vN0pQ8sT2wX5zA7cE9gH1mR4uY6bD0fL3nP5qS8v"
}

Returns 201. The secret is shown only here (and on rotation): store it to verify signatures. Needs a write key. Responses: 201, 400, 401, 403, 404, 429.

Retrieve a webhook endpoint​

GET /api/v1/customers/42/webhook-endpoints/9 HTTP/1.1
Host: app.gtmclarity.ai

Returns the endpoint object. Responses: 200, 401, 403, 404, 429.

Update a webhook endpoint​

PATCH /api/v1/customers/42/webhook-endpoints/9 HTTP/1.1
Host: app.gtmclarity.ai
Content-Type: application/json

{
"events": null,
"active": false
}

Any of url, description, events and active, with the same rules as create. Returns the updated endpoint. Needs a write key. Responses: 200, 400, 401, 403, 404, 429.

Delete a webhook endpoint​

DELETE /api/v1/customers/42/webhook-endpoints/9 HTTP/1.1
Host: app.gtmclarity.ai
{
"deleted": true,
"id": 9
}

Deletes the endpoint and its delivery history. To pause one instead, set active to false. Needs an admin key. Responses: 200, 401, 403, 404, 429.

Rotate a signing secret​

POST /api/v1/customers/42/webhook-endpoints/9/rotate-secret HTTP/1.1
Host: app.gtmclarity.ai

Returns 200 with { "endpoint": {...}, "secret": "whsec_..." }, the same shape as create. Deliveries are signed with the new secret from then on, retries included, so update your receiver straight away. Needs a write key. Responses: 200, 401, 403, 404, 429.

List deliveries​

One row per delivery attempt to the endpoint, newest first.

GET /api/v1/customers/42/webhook-endpoints/9/deliveries?limit=20 HTTP/1.1
Host: app.gtmclarity.ai
{
"data": [
{
"id": 2204,
"eventName": "conversion.recorded",
"attempt": 2,
"status": 500,
"ok": false,
"error": "http 500",
"createdAt": "2026-10-14T15:20:13.000Z",
"nextRetryAt": "2026-10-14T15:25:13.000Z"
}
],
"nextCursor": 2204
}
ParameterTypeNotes
limitinteger1 to 100, default 20
cursorintegerThe previous page's nextCursor
FieldTypeNotes
idinteger
eventNamestringOne of the event names above
attemptinteger1 to 5
statusinteger or nullThe HTTP status your endpoint returned; null when there was no response (for example, a timeout)
okbooleanWhether the attempt succeeded
errorstring or null
createdAtdate-time
nextRetryAtdate-time or nullWhen the next retry is due, if any

nextCursor is null on the last page. Responses: 200, 400, 401, 403, 404, 429.