Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nusomi.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks deliver Nusomi events to your HTTP endpoint. Use them to trigger downstream pipelines, alert on drift, or kick off recovery flows.

​
Create a webhook

POST /v1/webhooks

{
  "url": "https://acme.com/hooks/nusomi",
  "events": [
    "session.sealed",
    "session.error",
    "memory.drift.new_node",
    "export.completed"
  ],
  "description": "Ops pipeline trigger"
}

​
Response 201

{
  "id": "whk_01HZ...",
  "url": "https://acme.com/hooks/nusomi",
  "events": [...],
  "secret": "whsec_..."
}
The secret is returned once. Use it to verify signatures.

​
Event types

EventFired when
session.createdSession created (before start).
session.startedSession entered recording.
session.stoppedSession entered stopped.
session.sealedSession sealed and indexed.
session.errorSession ended with an error tag or detected failure.
session.taggedA tag was added.
replay.queued / .running / .completed / .diverged / .failedReplay lifecycle.
recovery.started / .succeeded / .failedRecovery lifecycle.
export.queued / .completed / .failedExport lifecycle.
memory.drift.new_nodeNew cluster appeared in the workflow graph.
memory.drift.path_disappearedA previously-common path stopped occurring.
quota.warning80% of monthly quota consumed.
quota.exhaustedQuota hit.

​
Payload shape

{
  "id": "evt_01HZ...",
  "type": "session.sealed",
  "created_at": "2026-05-07T14:01:33Z",
  "data": {
    "session": { "id": "ses_01HZ...", "workflow": "process_invoice", ... }
  }
}
The data envelope is type-specific. Treat unknown event types defensively — Nusomi may add new types in a backward-compatible release.

​
Signing

Each delivery includes: 
Nusomi-Signature: t=1715091600,v1=hex-signature,v1=hex-signature-old
Verify by computing HMAC-SHA256(secret, "{t}.{raw_body}") and comparing constant-time to v1. Multiple signatures are present during secret rotation. 
import crypto from "node:crypto";

function verify(secret: string, header: string, body: string) {
  const [tPart, ...sigParts] = header.split(",");
  const t = tPart.split("=")[1];
  const v1s = sigParts.filter((p) => p.startsWith("v1=")).map((p) => p.slice(3));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${body}`)
    .digest("hex");
  return v1s.some((sig) =>
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
  );
}

​
Delivery & retries

PropertyValue
MethodPOST
Content-Typeapplication/json
Timeout10 s
Retry policyExponential backoff: 5s, 30s, 5m, 30m, 2h, 6h, 12h
Max attempts7
IdempotencyNusomi-Delivery-Id header is unique per attempt; the id field is unique per event.
A 2xx response is treated as success. Anything else is retried.

​
Listing & inspecting

GET /v1/webhooks
GET /v1/webhooks/{id}
GET /v1/webhooks/{id}/deliveries
Each delivery records request / response status / duration / response body (truncated to 4 KB).

​
Replaying a delivery

POST /v1/webhooks/{id}/deliveries/{delivery_id}/redeliver
Pushes the same payload again with a fresh Nusomi-Delivery-Id.

​
Rotating the secret

POST /v1/webhooks/{id}/secret
Returns a new secret. The old secret keeps signing for 24 hours so you can roll your verifier.

​
Deleting

DELETE /v1/webhooks/{id}