Sokko Docs
Platform API

Webhooks

Register an endpoint, receive signed events for agents, turns, connections and credits, verify the signature, and handle retries.

A webhook tells your server that something happened, so that you do not have to poll: an agent is ready, a turn ended, an app was connected, a workspace was topped up.

Webhooks belong to your account. One endpoint receives the events of every workspace. All paths below are relative to https://sokko.ai/api/v1.

Create an endpoint

POST /webhooks
FieldTypeRules
urlstringRequired. An https URL on a public host, up to 2,048 characters, with no credentials.
eventsstring[]Optional. The event types to receive. Absent or empty: every type.
curl https://sokko.ai/api/v1/webhooks \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.acme.example/hooks/agents",
    "events": ["agent.ready", "agent.failed", "turn.completed", "turn.failed"]
  }'

The answer is 201:

{
  "webhook": {
    "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
    "url": "https://api.acme.example/hooks/agents",
    "events": ["agent.ready", "agent.failed", "turn.completed", "turn.failed"],
    "status": "active",
    "disabledReason": null,
    "createdAt": "2026-11-20T10:05:44.918Z",
    "updatedAt": "2026-11-20T10:05:44.918Z"
  },
  "secret": "whsec_4kq0mN8vJrX2yT7bWc5Zp1LhG9sDfA3eUoIi6RtYxQk="
}

secret is the signing secret of this endpoint. It is in this answer and in no later read. Store it now. If you lose it, rotate it.

An account holds at most 5 endpoints.

StatusCodeWhen
400invalid_requestThe URL is not https, has credentials, or its host is not public; or an unknown event type.
409conflictThe account already has 5 endpoints.
503unavailableThe secret could not be stored. Nothing was created. Try again later.

Manage endpoints

GET    /webhooks
GET    /webhooks/{webhookId}
PATCH  /webhooks/{webhookId}
DELETE /webhooks/{webhookId}

The list answers every endpoint, oldest first, as { "data": [...], "nextCursor": null }. A read answers the endpoint object, never the secret.

PATCH takes at least one of:

FieldMeaning
urlA new address. The secret stays.
eventsA new list of event types. [] means every type.
statusdisabled stops deliveries. active turns the endpoint on again and resets its count of failures.
curl -X PATCH https://sokko.ai/api/v1/webhooks/f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "active" }'

The answer is the endpoint object. disabledReason is disabled_by_caller when you disabled the endpoint and delivery_failures when the platform did.

A delete removes the endpoint, its secret and its delivery records:

{ "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b", "deleted": true }

Errors: 400 invalid_request, 404 not_found, 503 unavailable.

The request your endpoint receives

Each event is one POST with a JSON body:

POST /hooks/agents HTTP/1.1
Host: api.acme.example
Content-Type: application/json
User-Agent: platform-webhooks/1
webhook-id: 2c7e9a10-5b3d-4f8e-a1c6-9d0e2f4a6b8c
webhook-timestamp: 1795169145
webhook-signature: v1,K2pV0m3uQ8sYh1dZx7eRt5wNc9bAf4gLj6oIi2TqUvM=

{"id":"2c7e9a10-5b3d-4f8e-a1c6-9d0e2f4a6b8c","type":"agent.ready","createdAt":"2026-11-20T10:05:44.102Z","data":{"workspaceId":"7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11","agentId":"3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05","externalId":"order-desk"}}
Body fieldMeaning
idThe event id. The same on every endpoint and on every retry.
typeThe event type.
createdAtWhen the event happened.
dataIds and status values. See below.

Answer with any 2xx status within 10 seconds. Everything else is a failed attempt: another status, a redirect (it is not followed), a timeout, a connection error. The body of your answer is not read.

Do the work after you answer. Put the event on a queue, answer 200, then process it.

What data holds

data is a flat object of ids, status values and amounts. It never holds message text, instructions, recipe variables or anything an end user wrote. To get the content, call the API with the ids: for turn.completed, read the turn.

Event types

Agents

Sent for agents created through the Platform API.

TypeWhen
agent.readyThe agent's status became ready: after a create, a resume, a redeploy or a change that restarted it.
agent.failedThe agent could not start and the platform stopped trying, or the setup of a recipe agent failed.
agent.suspendedThe agent's status became suspended.
agent.upgradedAn upgrade to a newer recipe version finished.
agent.upgrade_failedAn upgrade that was accepted did not finish. The agent stays on its old version.
{
  "workspaceId": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
  "agentId": "3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05",
  "externalId": "order-desk"
}

externalId is null for an agent without one.

agent.upgrade_failed has one more field, code:

{
  "workspaceId": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
  "agentId": "3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05",
  "externalId": "order-desk",
  "code": "upgrade_timeout"
}

code is the lastError.code of the agent. See When an upgrade does not finish for its values. The event holds no message: read the agent for it.

An upgrade that was accepted (202) ends with agent.upgraded or with agent.upgrade_failed, unless the agent is deleted first. An upgrade request that is refused with an error status sends no event.

The upgrade itself never sends agent.failed. That event is about the agent: it is sent when the agent could not start and the platform stopped trying. So with the code agent_failed you can get both events, in any order. You get agent.upgrade_failed alone when the platform starts the agent again by itself and it comes back: agent.ready then follows. With every other code, no agent.failed is sent.

An agent that is deleted sends no event.

Turns

Sent when a turn of an API conversation ends.

TypeWhenstatus in data
turn.completedThe agent answered.completed
turn.input_requiredThe agent asked the end user a question and waits.waiting
turn.failedThe turn ended with no answer.failed, interrupted or cancelled
{
  "workspaceId": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
  "agentId": "3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05",
  "conversationId": "c41e8f2a-6b7d-4a90-b3c5-1e2f3a4b5c6d",
  "turnId": "9f2c1d3e-4b5a-4c6d-8e7f-0a1b2c3d4e5f",
  "status": "completed"
}

status has the values of the turn object of the API. A turn you stopped sends turn.failed with cancelled.

Read the answer with GET /workspaces/{workspaceId}/agents/{agentId}/conversations/{conversationId}/turns/{turnId}.

Connections

TypeWhen
connection.activeYour customer finished connecting an app.
connection.failedA connection attempt failed.

The event is sent when the browser comes back from the app, or when a read of the connection finds that the attempt has ended, whichever is first.

{
  "workspaceId": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
  "agentId": "3b9d7e0a-51c2-4f6d-8e1a-9c4b2d7f6a05",
  "connectionId": "d5f7a9c1-3e2b-4a6c-8d0e-1f2a3b4c5d6e",
  "app": "googlecalendar"
}

Credits

TypeWhen
credits.topped_upAn automatic top-up moved credits to a workspace.
credits.cap_reachedA top-up was due and the monthly cap stopped it. Sent once per workspace and month.

credits.topped_up:

{
  "workspaceId": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
  "amountCents": 2000,
  "balanceCents": 2412,
  "month": "2026-11",
  "monthTotalCents": 6000
}

credits.cap_reached:

{
  "workspaceId": "7d1f3c52-8a4e-4b9a-9c1d-2f6e8a0b4c11",
  "month": "2026-11",
  "monthlyCapCents": 10000,
  "monthTotalCents": 10000
}

amountCents is what this top-up moved, balanceCents the workspace's balance after it, month the calendar month (UTC) and monthTotalCents what the automatic top-ups of that month moved so far. credits.cap_reached has no amount: nothing moved.

A transfer you make yourself with POST .../credits sends no event.

Workspaces and recipe tests

TypeWhendata
workspace.deletedThe deletion of a workspace finished.workspaceId, externalId
test_run.completedA recipe test run ended.recipeId, testRunId, status

The status of test_run.completed is completed, failed or cancelled: the event is sent for every end of a run, not only for a good one.

What has no event

  • A scheduled task sends no event, neither when it starts nor when it ends. Read the schedules for the time and result of the last run.
  • A change you make through the API (a rename, a transfer, a new skill) sends no event. You already have the answer of the call.

Verify the signature

Anyone can send a POST to your URL. Verify every request before you trust it.

The signature is an HMAC-SHA256 over the text <webhook-id>.<webhook-timestamp>.<raw body>:

  • The key is your secret without the whsec_ prefix, decoded from base64.
  • The header webhook-signature is v1, followed by the HMAC in base64. It can hold several signatures separated by a space: accept the request when one matches.
  • Use the raw body, byte for byte as it arrived. A body that was parsed and serialized again does not match.
  • Refuse a request whose webhook-timestamp (seconds since 1970) is more than 5 minutes from your clock. This stops an old request from being replayed.

The scheme is Standard Webhooks, so its libraries verify these requests too.

import { createHmac, timingSafeEqual } from "node:crypto";

const TOLERANCE_SECONDS = 300;

// headers: lower-case header names. rawBody: the body as a string, not parsed.
export function verifyWebhook(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures || !/^\d+$/.test(timestamp)) return false;

  const age = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
  if (age > TOLERANCE_SECONDS) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const digest = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest("base64");
  const expected = Buffer.from(`v1,${digest}`);

  return signatures.split(" ").some((candidate) => {
    const given = Buffer.from(candidate);
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
}

With Node's built-in server:

import { createServer } from "node:http";

createServer(async (request, response) => {
  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks).toString("utf8");

  if (!verifyWebhook(process.env.SOKKO_WEBHOOK_SECRET, request.headers, rawBody)) {
    response.writeHead(401).end();
    return;
  }
  const event = JSON.parse(rawBody);
  await queue.add(event.id, event); // your own queue, keyed by the event id
  response.writeHead(200).end();
}).listen(8080);

In a framework that parses JSON for you, read the raw body for this route. In Express, use express.raw({ type: "application/json" }).

Retries and automatic disable

A failed attempt is sent again, with a longer wait each time:

After failed attemptWait before the next
11 minute
25 minutes
330 minutes
42 hours
56 hours
612 hours

The 7th failed attempt ends the delivery as failed. That is about 21 hours after the event.

  • Every retry has the same webhook-id and the same body. webhook-timestamp and the signature are new for each attempt.
  • Events can arrive out of order. Do not depend on the order: when you need the current state, read the resource.
  • When 20 attempts in a row fail, with no success between them, the endpoint becomes disabled with "disabledReason": "delivery_failures". The count is per endpoint and covers all its deliveries, so an endpoint that is down is disabled after 20 failed attempts in total, long before one delivery has used its 7 attempts. Its waiting deliveries end as failed.
  • A disabled endpoint receives nothing, and events that happen while it is disabled are not kept for later. Fix your endpoint, then turn it on with PATCH and "status": "active", and read the state you missed from the API.

Delivery is at least once

The platform sends each event until your endpoint answers 2xx, so the same event can reach you more than once. Two cases:

  • The same webhook-id again. Your answer was a 2xx, and the platform could not record it, or your answer came after the 10 seconds. The event is sent again with the same id and body.
  • A second event for the same fact, with a new webhook-id. Rare: the platform stopped between recording an event and the step after it, and repeated both. It can happen for workspace.deleted.

So do not key your handler on webhook-id alone. Make it safe to repeat on the resource ids: the type with workspaceId, agentId, turnId, connectionId or testRunId, and status where the event has one. Handling "turn X is completed" twice must do the work once.

"At least once" is about the delivery of a recorded event. An event is recorded right after the change it reports, so a fault on the platform's side at that moment can leave a change with no event. Treat a webhook as a signal to read the resource, and read the resource yourself when a wait takes longer than you expect.

Pace

Deliveries go out in batches every few seconds. One batch sends at most 2 deliveries to one endpoint, the oldest first. A burst of events therefore reaches you over some seconds, not at once, and an endpoint that answers slowly gets its events later. Answer fast, and do the work after you answer.

Send a test event

POST /webhooks/{webhookId}/test
curl -X POST https://sokko.ai/api/v1/webhooks/f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b/test \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"

The answer is 202 with the id of the event:

{ "eventId": "8b1d3f5a-7c9e-4a2b-8d4f-6e0a2c4e6f8b" }

The event goes to this endpoint only, within a few seconds, signed like every other event:

{
  "id": "8b1d3f5a-7c9e-4a2b-8d4f-6e0a2c4e6f8b",
  "type": "webhook.test",
  "createdAt": "2026-11-20T10:07:02.455Z",
  "data": { "webhookId": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b" }
}

webhook.test is not a type an endpoint subscribes to: it is sent whatever the events list says.

Errors: 404 not_found, 409 conflict (the endpoint is disabled).

Read the deliveries

GET /webhooks/{webhookId}/deliveries

The last 50 deliveries of the endpoint, newest first. Use it to see why an endpoint fails.

curl https://sokko.ai/api/v1/webhooks/f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b/deliveries \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{
  "data": [
    {
      "id": "0a9b8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
      "eventId": "2c7e9a10-5b3d-4f8e-a1c6-9d0e2f4a6b8c",
      "type": "agent.ready",
      "status": "pending",
      "attempts": 2,
      "responseStatus": 500,
      "error": "http_500",
      "nextAttemptAt": "2026-11-20T10:11:45.310Z",
      "createdAt": "2026-11-20T10:05:44.102Z",
      "updatedAt": "2026-11-20T10:06:45.310Z"
    }
  ],
  "nextCursor": null
}
FieldMeaning
statuspending (waits for its next attempt), delivered or failed.
attemptsAttempts made so far.
responseStatusThe HTTP status of the last attempt, or null when your host did not answer.
errorA short code for the last failure, or null.
nextAttemptAtWhen the next attempt is due. null once the delivery has ended.

Values of error: http_<status> (your host answered that status), timeout, connection_failed, unreachable, url_not_allowed (the host resolves to an address that is not public), endpoint_disabled, signing_secret_unavailable.

signing_secret_unavailable is on the platform's side: no request was sent, the attempt is tried again, and it does not count toward the 20 failed attempts.

A delivery record never holds the event's body or your answer's body. Records are removed after a time: 7 days for a delivered event, 30 days for a failed one.

Errors: 404 not_found.

Rotate the secret

POST /webhooks/{webhookId}/rotate-secret
curl -X POST https://sokko.ai/api/v1/webhooks/f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b/rotate-secret \
  -H "Authorization: Bearer $SOKKO_PLATFORM_KEY"
{
  "webhook": {
    "id": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
    "url": "https://api.acme.example/hooks/agents",
    "events": ["agent.ready", "agent.failed", "turn.completed", "turn.failed"],
    "status": "active",
    "disabledReason": null,
    "createdAt": "2026-11-20T10:05:44.918Z",
    "updatedAt": "2026-11-21T08:12:09.004Z"
  },
  "secret": "whsec_Zx9cV7bN5mQ3wE1rT8yU6iO4pA2sD0fGhJkL+zXcVbN="
}

The old secret stops at once: the next delivery is signed with the new one. To rotate with no refused event, make your endpoint accept both secrets for a short time, rotate, then drop the old one.

Errors: 404 not_found, 503 unavailable.

On this page