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"
}
| Field | Type | Notes |
|---|---|---|
id | integer | Ledger event id |
conversationId | integer | |
customerId | integer | |
type | string | booked_meeting, qualified_lead, sale, resolved_ticket, custom, captured_contact or qualified_meeting |
value | string or null | Details recorded with the conversion. Conversions the assistant records carry a JSON-encoded string; other sources can store plain text |
billedAt | date-time or null | null when not billed |
billedCents | integer or null | |
reversedAt | date-time or null | Set when the charge was reversed |
createdAt | date-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
| Parameter | Type | Notes |
|---|---|---|
limit | integer | 1 to 100, default 20 |
starting_after | integer | A conversion id |
customer_id | integer | Only this customer |
created_after | date-time | Only events created after this time |
billed | true or false | Whether billedAt is set |
type | string | One 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"
}
| Field | Type | Notes |
|---|---|---|
id | integer | |
customerId | integer | |
url | string | HTTPS URL |
description | string or null | |
events | array of strings or null | null means every event. Values: conversation.started, conversation.ended, identity.resolved, conversion.recorded, resolution.recorded, handoff.requested, outcome.marked |
active | boolean | Inactive endpoints receive nothing |
createdAt | date-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"]
}
| Field | Type | Notes |
|---|---|---|
url | string | Required. Must be https and resolve to a public address |
description | string or null | 1 to 500 characters |
events | array of strings or null | Omit 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
}
| Parameter | Type | Notes |
|---|---|---|
limit | integer | 1 to 100, default 20 |
cursor | integer | The previous page's nextCursor |
| Field | Type | Notes |
|---|---|---|
id | integer | |
eventName | string | One of the event names above |
attempt | integer | 1 to 5 |
status | integer or null | The HTTP status your endpoint returned; null when there was no response (for example, a timeout) |
ok | boolean | Whether the attempt succeeded |
error | string or null | |
createdAt | date-time | |
nextRetryAt | date-time or null | When the next retry is due, if any |
nextCursor is null on the last page. Responses: 200, 400, 401, 403, 404, 429.