Webhooks

Manage outbound webhook endpoints and inspect deliveries. Account-scoped: these endpoints ignore the key's node binding (unlike the read endpoints).

List the account's outbound webhook endpoints

get

Requires webhooks:manage. Signing secrets are never returned.

Authorizations

AuthorizationstringRequired

An API key created in Settings → API (ca_live_…).

Responses

200

application/json

401

Missing or invalid API key.

application/json

403

The key lacks the required scope, or the account's plan does not include it.

application/json

get/webhooks

GET /api/v4/webhooks HTTP/1.1
Host: app.customer-alliance.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "url": "https://example.com",
      "events": [
        "review.received"
      ],
      "is_active": true,
      "created_at": "2026-08-11T08:36:26.444Z",
      "updated_at": "2026-08-11T08:36:26.444Z"
    }
  ]
}

Register an outbound webhook endpoint

post

Requires webhooks:manage. The signing secret is returned exactly once — store it now.

Authorizations

AuthorizationstringRequired

An API key created in Settings → API (ca_live_…).

Body

namestring · min: 1 · max: 120Required

urlstring · uriRequired

Delivery URL. Must be http(s); private/reserved addresses are rejected at delivery time.

is_activebooleanOptional

PATCH only — pause/resume deliveries without deleting the endpoint.

Responses

201

Created — secret shown once.

application/json

secretstringRequired

The signing secret (whsec_…). Returned exactly once — store it now; you cannot retrieve it again.

Example: whsec_XXXXXXXXXXXXXXXXXXXXXXXX

400

Invalid request.

application/json

401

Missing or invalid API key.

application/json

403

The key lacks the required scope, or the account's plan does not include it.

application/json

409

Per-account endpoint limit reached.

application/json

post/webhooks

POST /api/v4/webhooks HTTP/1.1
Host: app.customer-alliance.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "name": "Prod integration",
  "url": "https://example.com/hooks/ca",
  "events": [
    "review.received",
    "survey.response_completed"
  ]
}

{
  "secret": "whsec_XXXXXXXXXXXXXXXXXXXXXXXX",
  "endpoint": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text",
    "url": "https://example.com",
    "events": [
      "review.received"
    ],
    "is_active": true,
    "created_at": "2026-08-11T08:36:26.444Z",
    "updated_at": "2026-08-11T08:36:26.444Z"
  }
}

Delete a webhook endpoint (cascades its deliveries)

delete

Requires webhooks:manage.

Authorizations

AuthorizationstringRequired

An API key created in Settings → API (ca_live_…).

Path parameters

idstring · uuidRequired

Responses

200

No content

401

Missing or invalid API key.

application/json

403

The key lacks the required scope, or the account's plan does not include it.

application/json

404

Not found or outside the key's scope.

application/json

delete/webhooks/{id}

DELETE /api/v4/webhooks/{id} HTTP/1.1
Host: app.customer-alliance.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Update a webhook endpoint

patch

Requires webhooks:manage. Any subset of name / url / events / is_active.

Authorizations

AuthorizationstringRequired

An API key created in Settings → API (ca_live_…).

Path parameters

idstring · uuidRequired

Body

namestring · min: 1 · max: 120Required

urlstring · uriRequired

Delivery URL. Must be http(s); private/reserved addresses are rejected at delivery time.

is_activebooleanOptional

PATCH only — pause/resume deliveries without deleting the endpoint.

Responses

200

No content

400

Invalid request.

application/json

401

Missing or invalid API key.

application/json

403

The key lacks the required scope, or the account's plan does not include it.

application/json

404

Not found or outside the key's scope.

application/json

patch/webhooks/{id}

PATCH /api/v4/webhooks/{id} HTTP/1.1
Host: app.customer-alliance.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 121

{
  "name": "Prod integration",
  "url": "https://example.com/hooks/ca",
  "events": [
    "review.received",
    "survey.response_completed"
  ]
}

No content

Recent delivery attempts for one endpoint (newest first)

get

Requires webhooks:manage.

Authorizations

AuthorizationstringRequired

An API key created in Settings → API (ca_live_…).

Path parameters

idstring · uuidRequired

Responses

200

application/json

401

Missing or invalid API key.

application/json

403

The key lacks the required scope, or the account's plan does not include it.

application/json

404

Not found or outside the key's scope.

application/json

get/webhooks/{id}/deliveries

GET /api/v4/webhooks/{id}/deliveries HTTP/1.1
Host: app.customer-alliance.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "event_type": "text",
      "status": "pending",
      "attempt_count": 1,
      "last_status_code": null,
      "last_attempt_at": null,
      "created_at": "2026-08-11T08:36:26.444Z"
    }
  ]
}

Send a test `ping` delivery to one endpoint

post

Requires webhooks:manage. Queues a signed ping regardless of the endpoint's subscribed events.

Authorizations

AuthorizationstringRequired

An API key created in Settings → API (ca_live_…).

Path parameters

idstring · uuidRequired

Responses

200

OK — ping queued.

No content

401

Missing or invalid API key.

application/json

403

The key lacks the required scope, or the account's plan does not include it.

application/json

404

Not found or outside the key's scope.

application/json

post/webhooks/{id}/test

POST /api/v4/webhooks/{id}/test HTTP/1.1
Host: app.customer-alliance.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

PreviousGuests NextWebhook Events

Last updated 7 days ago

Was this helpful?