Reference
Webhooks
Manage webhook endpoints and read the event catalogue.
Endpoints receive signed POST requests for the events they subscribe to. Signing, retries and verification code are in Webhooks.
List webhook endpoints
GET
/api/v1/webhooksScope webhooks:manageEndpoints of the workspace with their status and failure streak.
Example request
curl -s "https://app.graphkit.com/api/v1/webhooks" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY"Response 200
| Field | Type | Description |
|---|---|---|
data | array of object | The page of results, newest first. |
data[].id | string (uuid) | UUID. |
data[].workspaceId | string (uuid) | |
data[].url | string | Endpoint URL. |
data[].description | string or null | |
data[].events | array of string | Empty means every event. Values: account.connected, account.disconnected, account.reconnect_required, lead.created, lead.replied, invitation.accepted, message.received, message.sent, campaign.started, campaign.completed, enrollment.completed, enrollment.stopped, email.replied, email.bounced, email.unsubscribed. |
data[].status | string | Current status. One of active, disabled. |
data[].disabledReason | string or null | |
data[].disabledAt | string (date-time) or null | |
data[].failureCount | integer | Consecutive failed attempts. |
data[].failingSince | string (date-time) or null | |
data[].lastSuccessAt | string (date-time) or null | |
data[].lastFailureAt | string (date-time) or null | |
data[].createdAt | string (date-time) | When it was created (RFC 3339, UTC). |
data[].stats | object | |
data[].stats.succeeded | integer | |
data[].stats.retrying | integer | |
data[].stats.dead | integer | |
nextCursor | string or null | Pass back as cursor for the next page; null on the last page. |
{
"data": [
{
"id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
"workspaceId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
"url": "https://hooks.example.com/graphkit",
"description": null,
"events": [
"account.connected",
"account.disconnected"
],
"status": "active",
"disabledReason": null,
"disabledAt": null,
"failureCount": 0,
"failingSince": null,
"lastSuccessAt": "2026-11-15T10:04:05Z",
"lastFailureAt": null,
"createdAt": "2026-11-15T10:04:05Z",
"stats": {
"succeeded": 12,
"retrying": 12,
"dead": 12
}
}
],
"nextCursor": null
}Errors
| Status | Code and meaning |
|---|---|
| 401 | invalid_api_key: the key is missing, unknown or revoked. |
| 403 | insufficient_scope: the key lacks the scope this endpoint needs. |
| 429 | rate_limited: more than 300 requests in a minute; wait for Retry-After. |
Create a webhook endpoint
POST
/api/v1/webhooksScope webhooks:manageCreates an endpoint. An empty events list subscribes to every event. The whsec_ signing secret is returned once, in this response only. In production the URL must use https and resolve to a public address.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
Idempotency-Key | header | string | Replays the stored response for 24 hours (header Idempotent-Replayed: true). Reusing a key with a different request is 422; while the first request runs, 409. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | https required in production. |
description | string | No | Up to 200 characters. |
events | array of string | No | Event types. Empty means every event. Values: account.connected, account.disconnected, account.reconnect_required, lead.created, lead.replied, invitation.accepted, message.received, message.sent, campaign.started, campaign.completed, enrollment.completed, enrollment.stopped, email.replied, email.bounced, email.unsubscribed. |
Example request
curl -s -X POST "https://app.graphkit.com/api/v1/webhooks" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"url":"https://hooks.example.com/graphkit","description":"CRM sync","events":["lead.replied","message.received"]}'Response 201
| Field | Type | Description |
|---|---|---|
id | string (uuid) | UUID. |
workspaceId | string (uuid) | |
url | string | Endpoint URL. |
description | string or null | |
events | array of string | Empty means every event. Values: account.connected, account.disconnected, account.reconnect_required, lead.created, lead.replied, invitation.accepted, message.received, message.sent, campaign.started, campaign.completed, enrollment.completed, enrollment.stopped, email.replied, email.bounced, email.unsubscribed. |
status | string | Current status. One of active, disabled. |
disabledReason | string or null | |
disabledAt | string (date-time) or null | |
failureCount | integer | Consecutive failed attempts. |
failingSince | string (date-time) or null | |
lastSuccessAt | string (date-time) or null | |
lastFailureAt | string (date-time) or null | |
createdAt | string (date-time) | When it was created (RFC 3339, UTC). |
stats | object | |
stats.succeeded | integer | |
stats.retrying | integer | |
stats.dead | integer | |
secret | string | whsec_… signing secret, shown once. |
{
"id": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
"workspaceId": "0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99",
"url": "https://hooks.example.com/graphkit",
"description": null,
"events": [
"account.connected",
"account.disconnected"
],
"status": "active",
"disabledReason": null,
"disabledAt": null,
"failureCount": 0,
"failingSince": null,
"lastSuccessAt": "2026-11-15T10:04:05Z",
"lastFailureAt": null,
"createdAt": "2026-11-15T10:04:05Z",
"stats": {
"succeeded": 12,
"retrying": 12,
"dead": 12
},
"secret": "whsec_7d1f..."
}Errors
| Status | Code and meaning |
|---|---|
| 401 | invalid_api_key: the key is missing, unknown or revoked. |
| 403 | insufficient_scope: the key lacks the scope this endpoint needs. |
| 429 | rate_limited: more than 300 requests in a minute; wait for Retry-After. |
Delete a webhook endpoint
DELETE
/api/v1/webhooks/{id}Scope webhooks:manageDeletes the endpoint. It receives no further deliveries.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id | path | string (uuid) | The resource id. |
Example request
curl -s -X DELETE "https://app.graphkit.com/api/v1/webhooks/0193a5b2-7c1e-7a10-9f2a-2b3c4d5e6f99" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY"Response 204
Deleted.
Errors
| Status | Code and meaning |
|---|---|
| 401 | invalid_api_key: the key is missing, unknown or revoked. |
| 403 | insufficient_scope: the key lacks the scope this endpoint needs. |
| 404 | not_found: no such resource in this key's workspace. |
| 429 | rate_limited: more than 300 requests in a minute; wait for Retry-After. |
List event types
GET
/api/v1/webhook-eventsScope workspace:readThe event catalogue, with a description and an example data object for each type.
Example request
curl -s "https://app.graphkit.com/api/v1/webhook-events" \
-H "Authorization: Bearer $GRAPHKIT_API_KEY"Response 200
| Field | Type | Description |
|---|---|---|
data | array of object | The page of results, newest first. |
data[].type | string | One of account.connected, account.disconnected, account.reconnect_required, lead.created, lead.replied, invitation.accepted, message.received, message.sent, campaign.started, campaign.completed, enrollment.completed, enrollment.stopped, email.replied, email.bounced, email.unsubscribed. |
data[].group | string | |
data[].description | string | |
data[].example | object | |
nextCursor | string or null | Pass back as cursor for the next page; null on the last page. |
{
"data": [
{
"type": "account.connected",
"group": "leads",
"description": "string",
"example": {}
}
],
"nextCursor": null
}Errors
| Status | Code and meaning |
|---|---|
| 401 | invalid_api_key: the key is missing, unknown or revoked. |
| 403 | insufficient_scope: the key lacks the scope this endpoint needs. |
| 429 | rate_limited: more than 300 requests in a minute; wait for Retry-After. |