Errors
The RFC 9457 problem details format that every CentraKit API and MCP error uses, how codes and statuses are derived, and how to handle APPROVAL_REQUIRED.
MCP server
Connect AI clients to the CentraKit product MCP server and the docs MCP server, with OAuth setup, scopes, approvals and the full list of 74 product tools.
Errors
The RFC 9457 problem details format that every CentraKit API and MCP error uses, how codes and statuses are derived, and how to handle APPROVAL_REQUIRED.
MCP server
Connect AI clients to the CentraKit product MCP server and the docs MCP server, with OAuth setup, scopes, approvals and the full list of 74 product tools.
Send signed CentraKit events to your HTTPS endpoints and receive external webhooks that start workflows, including signatures, secret and token rotation, delivery retries, and the REST and MCP operations.
CentraKit has two kinds of webhooks per organization:
POST requests when events happen in CentraKit.webhook.received event that starts matching workflows.Manage both in the SaaS app under Integrations, on the Webhooks integration. It lists Incoming endpoints and Outgoing destinations, with New incoming webhook and New outgoing webhook actions that open /{orgSlug}/integrations/webhooks/incoming/create and /{orgSlug}/integrations/webhooks/outgoing/create. Everything is also available through the REST API and the MCP server.
| Concept | Description |
|---|---|
| Destination | An outgoing target: name, HTTPS URL, subscribed event kinds and an enabled flag. It has a whsec_ signing secret. |
| Endpoint | An incoming receiver: name, optional bound workflow definition and an enabled flag. It has a wh_ URL token and a whsec_ secret. |
| Delivery | One queued outgoing request to a destination, with its attempts and the last observed response. |
| Event kind | The event name a destination subscribes to, such as invoice.paid or task.completed. |
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
https://api.centrakit.com/api/v1/organizations/$ORG_ID/webhooks/destinations \
-d '{
"name": "ERP sync",
"url": "https://erp.example.com/hooks/centrakit",
"eventKinds": ["invoice.paid", "order.shipped"]
}'The URL must use HTTPS. The 201 response includes the destination and its secret. Store the secret now: list and get responses never return it, and only an explicit rotation returns a new one.
eventKinds defaults to an empty list. A destination with no event kinds receives no event deliveries; it only gets test sends and workflow webhook actions, and the overview shows it as Workflow only.
The destination form offers these event kinds, which are the same domain events workflows can trigger on:
| Area | Event kinds |
|---|---|
| Quotes | quote.sent, quote.viewed, quote.accepted, quote.rejected, quote.changes-requested, quote.expired, quote.withdrawn, quote.deposit-paid |
| Invoices | invoice.sent, invoice.viewed, invoice.overdue, invoice.reminder-sent, invoice.partially-paid, invoice.paid, invoice.uncollectible, invoice.cancelled, invoice.payment-failed, invoice.disputed, invoice.reminders-paused, invoice.reminders-resumed |
| Orders | order.created, order.confirmed, order.paid, order.backordered, order.shipped, order.ready-for-pickup, order.delivered, order.picked-up, order.fulfilled, order.invoiced, order.completed, order.returned, order.cancelled |
| Shipments | shipment.shipped, shipment.out-for-delivery, shipment.ready-for-pickup, shipment.delivered, shipment.exception |
| Purchase orders | purchase-order.sent, purchase-order.in-transit, purchase-order.partially-received, purchase-order.received, purchase-order.overdue, purchase-order.cancelled |
| Inventory | inventory.low-stock, inventory.out-of-stock, inventory.back-in-stock, inventory.level-changed |
| Promotions | promotion.expiring, promotion.limit-reached |
| Tasks | task.created, task.assigned, task.status-changed, task.stage-changed, task.completed, task.due-soon, task.overdue |
| Agenda | agenda.item.created, agenda.item.updated, agenda.item.deleted |
| Customers | customer.created, customer.lookup.requested |
| Other | knowledge.file.ingest-requested, product.lookup.requested, inbox.message.received, billing.usage-threshold, workflow.run.failed, webhook.received |
The API accepts any event kind string up to 160 characters, but only the kinds above are published.
Two more kinds appear in delivery logs without a subscription: webhook.test for the Send test action on a destination, and workflow.action for a workflow step that sends a webhook to a destination.
Each delivery is a POST to the destination URL:
POST /hooks/centrakit HTTP/1.1
Content-Type: application/json
Idempotency-Key: 9b2f0c1e-6a3d-4f7e-8b19-2c4d5e6f7a80
X-Centrakit-Timestamp: 1790000000
X-Centrakit-Signature: v1=5f2b...e91c
{"invoiceId":"...","status":"paid"}| Header | Value |
|---|---|
Content-Type | application/json |
Idempotency-Key | The delivery ID. It stays the same across retries of one delivery. |
X-Centrakit-Timestamp | Unix time in seconds when the request was signed. |
X-Centrakit-Signature | v1= followed by the hex HMAC-SHA256 of {timestamp}.{body} with the destination secret. |
The body is the event payload as JSON. There is no envelope and no event-kind header. To tell event kinds apart, read identifying fields from the payload or create one destination per event kind.
Compute the HMAC over the raw request body, compare in constant time, and reject old timestamps:
import { createHmac, timingSafeEqual } from "node:crypto";
export function verifyCentrakitWebhook(input: {
body: string;
secret: string;
signature: string | null;
timestamp: string | null;
}): boolean {
if (!input.signature || !input.timestamp) return false;
const age = Math.abs(Date.now() / 1000 - Number(input.timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = `v1=${createHmac("sha256", input.secret)
.update(`${input.timestamp}.${input.body}`)
.digest("hex")}`;
const a = Buffer.from(expected);
const b = Buffer.from(input.signature);
return a.length === b.length && timingSafeEqual(a, b);
}Use the Idempotency-Key header to ignore a delivery you already processed.
Events are queued as deliveries for every enabled destination subscribed to the event kind. The /api/v1/internal/webhook-deliveries job runs every minute, claims up to 25 due deliveries, and sends them:
| Outcome | Result |
|---|---|
2xx response | completed. |
429 or 5xx response, or a network error | failed, retried with backoff. |
Any other 4xx response | dead_lettered. No retry. |
| URL blocked by the outbound request policy | dead_lettered. No retry. |
| Destination disabled when the delivery is due | canceled. |
| Destination or its secret cannot be loaded | dead_lettered. |
A delivery gets at most 5 attempts. The waits after attempts 1 to 4 are 30, 60, 120 and 240 seconds, and the job picks the delivery up on its next run after that. A fifth failure dead-letters the delivery. CentraKit stores the response status, the first 2,000 characters of the response body, the error and the duration on each delivery.
Delivery statuses are pending, processing, completed, failed, dead_lettered and canceled. In the app, the deliveries table on a destination has a Retry action that queues a delivery again right away. Retry does not reset the attempt count, so a delivery that already used 5 attempts is dead-lettered again if the next attempt fails. Send test queues a webhook.test delivery with { "kind": "webhook.test", "sentAt": "..." }.
Workflow webhook actions send their request immediately from the workflow run, signed the same way, and record it as a workflow.action delivery.
POST /webhooks/destinations/{destinationId}/rotate-secret replaces the secret and returns the new one once. Deliveries sent after rotation use the new secret, so update your receiver at the same time.
curl -X POST \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
https://api.centrakit.com/api/v1/organizations/$ORG_ID/webhooks/endpoints \
-d '{ "name": "Shop orders" }'The 201 response includes the endpoint, its token and its secret. The receiving URL is:
https://api.centrakit.com/api/v1/public/webhooks/{token}List and get responses return neither the token nor the secret. Only creation and the matching rotation return them. Pass workflowDefinitionId to bind the endpoint to one workflow.
The receiver accepts a POST with a body of at most 256 KB. Authenticate each request in one of two ways:
X-Centrakit-Timestamp and X-Centrakit-Signature: v1=<hex>, the HMAC-SHA256 of {timestamp}.{body} with the endpoint secret. The timestamp must be within 5 minutes of the server clock. The header may list several comma-separated signatures, and the request is accepted when one matches.X-Webhook-Secret or as Authorization: Bearer <secret>.When a signature header is present it must verify on its own; the shared secret is not used as a fallback.
BODY='{"orderId":"ord_123"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://api.centrakit.com/api/v1/public/webhooks/$WEBHOOK_TOKEN" \
-H "Content-Type: application/json" \
-H "X-Centrakit-Timestamp: $TS" \
-H "X-Centrakit-Signature: v1=$SIG" \
-H "Idempotency-Key: ord_123" \
-d "$BODY"A valid request answers 202:
{
"ok": true,
"eventId": "5b657e4b-6f4b-4e5f-8c03-c0bc0d3f5f4a",
"runId": "6c768f5c-7f5c-4f60-9d14-d1cd1e40665b"
}runId is null when no workflow started. Send an Idempotency-Key header to deduplicate retries from your side.
{ "body": <value> }, and non-JSON text as { "body": "<text>" }.endpointId and publishes a webhook.received event for the organization.webhook.received receive the payload as well.Each endpoint tracks receiveCount, lastReceivedAt and lastStatus (accepted, unauthorized, disabled or failed).
| Status | Code | Cause |
|---|---|---|
| 401 | UNAUTHORIZED | Missing or wrong signature or secret, or a stale timestamp. |
| 404 | NOT_FOUND | Unknown token. |
| 404 | DISABLED | The endpoint is disabled. |
| 413 | PAYLOAD_TOO_LARGE | The body is larger than 256 KB. |
| 429 | RATE_LIMITED | More than 60 requests per minute for one token and client IP. The retry-after header says when to try again. |
| 500 | FAILED | The event could not be published. |
POST /webhooks/endpoints/{endpointId}/rotate-secret returns a new secret once. Senders must switch to it.POST /webhooks/endpoints/{endpointId}/rotate-token returns a new token and invalidates the previous URL immediately.| Permission | Allows |
|---|---|
organization.webhooks.view | Listing and reading destinations, endpoints and deliveries. |
organization.webhooks.create | Creating destinations and endpoints. |
organization.webhooks.update | Updating, rotating secrets and tokens, sending tests and retrying. |
organization.webhooks.delete | Deleting destinations and endpoints. |
The MCP server exposes every webhook operation as a tool:
listWebhookDeliveries, getWebhookDeliverylistWebhookDestinations, createWebhookDestination, getWebhookDestination, updateWebhookDestination, deleteWebhookDestination, rotateWebhookDestinationSecretlistWebhookEndpoints, createWebhookEndpoint, getWebhookEndpoint, updateWebhookEndpoint, deleteWebhookEndpoint, rotateWebhookEndpointSecret, rotateWebhookEndpointTokenThe mutation tools require the mcp:write scope and can be held for approval. See Workflows for webhook triggers and the send-webhook action.
Paths are relative to /api/v1/organizations/{organizationId}.
| Operation | Method and path |
|---|---|
listWebhookDestinations | GET /webhooks/destinations |
createWebhookDestination | POST /webhooks/destinations |
getWebhookDestination | GET /webhooks/destinations/{destinationId} |
updateWebhookDestination | PATCH /webhooks/destinations/{destinationId} |
deleteWebhookDestination | DELETE /webhooks/destinations/{destinationId} |
rotateWebhookDestinationSecret | POST /webhooks/destinations/{destinationId}/rotate-secret |
listWebhookEndpoints | GET /webhooks/endpoints |
createWebhookEndpoint | POST /webhooks/endpoints |
getWebhookEndpoint | GET /webhooks/endpoints/{endpointId} |
updateWebhookEndpoint | PATCH /webhooks/endpoints/{endpointId} |
deleteWebhookEndpoint | DELETE /webhooks/endpoints/{endpointId} |
rotateWebhookEndpointSecret | POST /webhooks/endpoints/{endpointId}/rotate-secret |
rotateWebhookEndpointToken | POST /webhooks/endpoints/{endpointId}/rotate-token |
listWebhookDeliveries | GET /webhooks/deliveries (optional destinationId filter) |
getWebhookDelivery | GET /webhooks/deliveries/{deliveryId} |
receivePublicWebhook | POST /api/v1/public/webhooks/{token} (no session) |
List operations use the standard offset and limit pagination. Each operation has a generated reference page; see OpenAPI.
Last updated on
Errors
The RFC 9457 problem details format that every CentraKit API and MCP error uses, how codes and statuses are derived, and how to handle APPROVAL_REQUIRED.
MCP server
Connect AI clients to the CentraKit product MCP server and the docs MCP server, with OAuth setup, scopes, approvals and the full list of 74 product tools.