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:manage

Endpoints 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

FieldTypeDescription
dataarray of objectThe page of results, newest first.
data[].idstring (uuid)UUID.
data[].workspaceIdstring (uuid)
data[].urlstringEndpoint URL.
data[].descriptionstring or null
data[].eventsarray of stringEmpty 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[].statusstringCurrent status. One of active, disabled.
data[].disabledReasonstring or null
data[].disabledAtstring (date-time) or null
data[].failureCountintegerConsecutive failed attempts.
data[].failingSincestring (date-time) or null
data[].lastSuccessAtstring (date-time) or null
data[].lastFailureAtstring (date-time) or null
data[].createdAtstring (date-time)When it was created (RFC 3339, UTC).
data[].statsobject
data[].stats.succeededinteger
data[].stats.retryinginteger
data[].stats.deadinteger
nextCursorstring or nullPass 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

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Create a webhook endpoint

POST/api/v1/webhooksScope webhooks:manage

Creates 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

NameInTypeDescription
Idempotency-KeyheaderstringReplays 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

FieldTypeRequiredDescription
urlstringYeshttps required in production.
descriptionstringNoUp to 200 characters.
eventsarray of stringNoEvent 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

FieldTypeDescription
idstring (uuid)UUID.
workspaceIdstring (uuid)
urlstringEndpoint URL.
descriptionstring or null
eventsarray of stringEmpty 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.
statusstringCurrent status. One of active, disabled.
disabledReasonstring or null
disabledAtstring (date-time) or null
failureCountintegerConsecutive failed attempts.
failingSincestring (date-time) or null
lastSuccessAtstring (date-time) or null
lastFailureAtstring (date-time) or null
createdAtstring (date-time)When it was created (RFC 3339, UTC).
statsobject
stats.succeededinteger
stats.retryinginteger
stats.deadinteger
secretstringwhsec_… 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

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

Delete a webhook endpoint

DELETE/api/v1/webhooks/{id}Scope webhooks:manage

Deletes the endpoint. It receives no further deliveries.

Parameters

NameInTypeDescription
idpathstring (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

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
404not_found: no such resource in this key's workspace.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

List event types

GET/api/v1/webhook-eventsScope workspace:read

The 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

FieldTypeDescription
dataarray of objectThe page of results, newest first.
data[].typestringOne 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[].groupstring
data[].descriptionstring
data[].exampleobject
nextCursorstring or nullPass back as cursor for the next page; null on the last page.
{
  "data": [
    {
      "type": "account.connected",
      "group": "leads",
      "description": "string",
      "example": {}
    }
  ],
  "nextCursor": null
}

Errors

StatusCode and meaning
401invalid_api_key: the key is missing, unknown or revoked.
403insufficient_scope: the key lacks the scope this endpoint needs.
429rate_limited: more than 300 requests in a minute; wait for Retry-After.

On this page