Skip to main content

Webhooks

Push, instead of polling. Register an HTTPS endpoint, subscribe it to the events you care about, and naturali POSTs a signed JSON envelope to it whenever one of them happens.

Overview​

A webhook is an endpoint plus a subscription. A delivery is one event addressed to one endpoint, along with everything that happened to it — how many attempts, what status came back, what the receiver said.

Three things are true of every delivery, and they are the reason this is a module rather than an outbound fetch:

  • It is recorded before it is attempted. The delivery row is committed first, so an event survives a receiver being down and survives naturali restarting mid-request.
  • It is retried. A non-2xx or a connection failure is retried with exponential backoff, up to five attempts, and a delivery that exhausts them can still be replayed by hand.
  • It is signed. X-Naturali-Signature carries a timestamped HMAC-SHA256 over the exact request body. Verify it before you act on a payload.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Webhooks.

Data Model​

Webhook​

FieldTypeDescription
idstringPublic webhook ID (whk_ prefix).
project_idstringThe owning project.
urlstring (uri)Where deliveries are POSTed: an https:// URL on a public internet host. A host that is, or resolves to, a loopback, private or link-local address is refused, at save and at each delivery; redirects are not followed.
eventsstring[]Which events this endpoint receives. Each entry is an exact type (generations.completed), a resource wildcard (generations.*), or * for everything. A bare resource name (generation) matches nothing and is rejected.
descriptionstring, nullableOperator-facing label.
activebooleanWhether deliveries are attempted.
created_atstring (date-time)
updated_atstring (date-time)
secretstringThe signing key, returned only by create and rotate. A generated one carries the whsec_ prefix; a chosen one is returned as sent. Never readable afterwards.

Delivery​

FieldTypeDescription
idstringPublic delivery ID (whd_ prefix). Sent with the request as X-Naturali-Delivery.
project_idstringThe owning project.
webhook_idstringThe endpoint the delivery is addressed to.
event_idstringThe event's id; shared by every delivery and redelivery of it.
typestringA naturali event type. Its values are what this API emits — deliberately only the events it can itself cause, so no declared name is one that never fires. It grows as modules land.
payloadobjectThe envelope POSTed to your endpoint. It is also what a delivery's payload holds, byte for byte, so the signed body and the recorded one are the same document.
statuspending | success | failedpending until a 2xx is received (success) or the attempts are exhausted (failed). A failed delivery can be replayed with …:redeliver.
status_codeinteger, nullableThe receiver's HTTP status on the last attempt; null when the attempt never got a response (DNS, TLS, refused, timed out).
attemptsintegerAttempts made so far.
next_attempt_atstring (date-time), nullableWhen the next retry is due; null once the delivery is terminal.
last_attempt_atstring (date-time), nullable
response_bodystring, nullableA truncated snippet of the receiver's response, or the transport error when there was no response.
created_atstring (date-time)
updated_atstring (date-time)

Event envelope​

The body POSTed to your endpoint, and the value of a delivery's payload:

{
"id": "evt_V1StGXR8Z5jdHi6B",
"type": "generations.completed",
"project_id": "proj_V1StGXR8Z5jdHi6B",
"resource_type": "generation",
"resource_id": "gen_V1StGXR8Z5jdHi6B",
"data": { "id": "gen_V1StGXR8Z5jdHi6B", "status": "completed" },
"created_at": "2026-07-31T00:00:00.000Z"
}

data is the resource shaped exactly as its own API returns it — a generations.completed payload carries the same object GET /v1/projects/{project_id}/generations/{generation_id} would — so a receiver rarely needs a follow-up call.

Event catalog​

EventFires whendata
conversations.startedAn address's first message on a channel opens a dialogue.The conversation.
messages.receivedAn inbound message reaches a bound agent.conversation_id, channel_id, channel, identifier (the address identifier, whatsapp:dm:<phone>), session_id, provider_message_id, content.
generations.completedA generation finishes.The generation record.
generations.failedA generation ends in failure.The same.
usage_thresholds.crossedA usage threshold the project set is crossed.The threshold record, plus observed_value.
projects.pausedThe project is paused.The project, as its GET reads it less your role.
projects.resumedThe project is resumed.The same, with paused_at and pause_reason null.
decisions.completedA decision settles with its answers.The decision.
decisions.failedA decision settles without answers.The decision, carrying error.
tasks.createdA task is opened.The task, as its GET reads it.
tasks.transitionedA task moves to a new state.The task, plus transition and from_state.
tasks.closedA task reaches a terminal state.The task.
tasks.migratedA task moves onto a newer workflow version.The task, plus from_state and from_workflow_version.
tasks.stalledA task passes its stall threshold without progress.The task.
tasks.pausedA task's automation is paused.The task.
tasks.resumedA task's automation is resumed.The task.
tasks.approval_failedAn approved transition can no longer apply.The task, plus transition and error_code.
tasks.automation_retryingA task's automation is retried.The task, plus attempt, max_attempts, error, generation_id and orchestration_run_id.
tasks.automation_rejectedA task's automation rejects the task.The task, plus result, transition and error_code.
tasks.automation_unroutedA task's automation matches no route.The task, plus result.
tasks.unblockedA task's last open dependency closes, is removed or is deleted.The task, plus unblocked_by: { task_id, state } of the dependency that freed it.
approvals.createdAn approval is raised.The approval item.
approvals.approvedAn approval is approved.The same.
approvals.rejectedAn approval is rejected.The same.
approvals.expiredAn approval passes expires_at unanswered.The same.
exceptions.createdAn exception is filed, not when an open one recurs.The exception item, as its GET reads it.

This list is the whole contract. Subscribing to a name that is not on it is rejected at registration rather than accepted and silently never delivered — an endpoint that looks connected and never fires is indistinguishable from one where nothing has happened yet.

An event is declared only when this API can cause it: a module this API does not serve contributes none.

Every name is <resource plural>.<verb>, the runtime's form. An event relayed from the runtime keeps the runtime's name, so tasks.unblocked here is tasks.unblocked there.

One thing worth knowing before you design against it: the two generations.* events arrive from the runtime, not from a naturali request. They are relayed onto the same bus by the platform's ingress the moment a run settles, so they fire for a background, blocking or streamed generation alike — including one started by a channel message, where no client is waiting on the response.

Key Concepts​

Subscriptions: exact, wildcard, or everything​

Each entry in events is one of three things:

EntrySelects
generations.completedExactly that event.
generations.*Every generations event, including ones added later.
*Everything.

A bare resource name (generations, with no .*) matches nothing and is rejected — the near-miss that would otherwise look like a working subscription.

Verifying a delivery​

Every request carries three headers:

HeaderValue
X-Naturali-EventThe event type.
X-Naturali-DeliveryThe delivery id (whd_…) — unique per attempt-chain.
X-Naturali-Signaturet=<unix seconds>,v1=<hex hmac>

The HMAC-SHA256 is computed over "<t>.<raw request body>" with your signing secret. Compute the same string, compare in constant time, and reject anything whose t is outside a window you choose — five minutes is a good default:

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

const verify = (rawBody, header, secret, toleranceSeconds = 300) => {
const parts = Object.fromEntries(
header.split(',').map((entry) => entry.trim().split('='))
);
const timestamp = Number(parts.t);
if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

const expected = createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
const a = Buffer.from(expected);
const b = Buffer.from(parts.v1 ?? '');
return a.length === b.length && timingSafeEqual(a, b);
};

Sign the raw bytes, before any JSON parsing or re-serialization — a framework that reformats the body will break the digest.

The timestamp is inside the signed string rather than merely alongside it, which is what makes the replay window enforceable: a captured delivery stops verifying once it ages out.

The secret is returned twice, ever​

Create returns it, rotate returns it, and no endpoint reads it back. It is encrypted at rest, but that would buy nothing if an API-key-authenticated GET would hand it over — the key would simply become as good as the secret.

The cost is worth stating plainly: a lost secret is rotated, not recovered. Rotation takes effect on the next delivery, including retries of deliveries already queued, and there is no window in which both secrets verify — so roll the new one out to your receiver promptly. If you want to cut over gradually, register a second endpoint instead and delete the first once traffic has moved.

Choosing the secret yourself​

Send secret on create or PATCH and deliveries are signed with that value instead of a generated one: 32 to 256 characters, no whitespace. Create echoes it back; PATCH does not. It is what lets a receiver be configured before the endpoint exists, and it is required when the endpoint is declared in a formation, where a deploy has no response to return a generated one in.

Retries, and what failed means​

A delivery is attempted up to five times: immediately, then with exponential backoff and jitter — roughly five minutes of trying in total. Any non-2xx is retried, not just a 5xx: a receiver answering 400 is far more often mid-deploy or mis-configured than making a considered judgement about the payload.

After the last attempt the delivery is failed. Nothing is lost — the payload is kept, and POST /v1/projects/{project_id}/webhook-deliveries/{delivery_id}:redeliver sends it again. Redelivery creates a new delivery and leaves the original's history intact, since that history is the evidence you redelivered on.

A success or failed delivery is kept for 30 days from when it was created, then deleted; past that it can no longer be read or redelivered. A pending delivery is kept until it settles.

Two consequences for your receiver:

  • Answer fast, work later. Respond 2xx as soon as you have durably accepted the event; a request that takes longer than ten seconds is abandoned and retried.
  • Expect duplicates. A receiver that answers slowly, or one you redeliver to, will see an event twice. Dedupe on the event's id, which is stable across redeliveries — X-Naturali-Delivery deliberately is not.

Turning an endpoint off without losing its history​

active: false stops deliveries and keeps the endpoint and its delivery log: pending deliveries fail unsent, and redelivering answers 409 WEBHOOK_INACTIVE until it is active again. It is the reversible half of DELETE /v1/projects/{project_id}/webhooks/{webhook_id}, and what to reach for while a receiver is being repaired. DELETE removes the endpoint and its deliveries.

Who may register one​

Every route needs the member role in the project — see Membership and the billing owner.

A narrowed key also needs, on a create or an update, the action that reads each event type its events select, on the whole type: a delivery carries the resource, so an endpoint never receives what its writer may not read. Missing any is 403 POLICY_GRANT_NOT_HELD, each one in meta.ungranted. An update is checked against the subscription it leaves; * needs every row. A key holds usage:ListThresholds through projects:ListProjectUsageThresholds, so usage_thresholds.* and * need that capability.

EventsRead action
conversations.*channels:GetChannelConversation on channel
messages.*channels:ListChannelConversationMessages on channel
generations.*generations:GetGeneration on generation
usage_thresholds.*usage:ListThresholds on usage
projects.*projects:GetProject on the whole project
decisions.*deciders:GetDecision on decision
tasks.*tasks:GetTask on task
approvals.*approvals:GetApproval on approval
exceptions.*exceptions:GetException on exception

How many a project holds​

At most 20 webhooks, on every plan, inactive ones included. Registering one more answers 409 WEBHOOK_LIMIT_REACHED with the ceiling in meta.limit; delete an endpoint to free its slot.

Formations​

A webhook is declarable as a webhook resource in a formation template, so the endpoint a stack's events are pushed to is planned, updated and deleted with the stack. The type is naturali's webhook, not the runtime's built-in of the same name. Its properties are WebhookResourceProperties in the formations spec: the fields POST /v1/projects/{project_id}/webhooks takes, with secret required.

parameters:
WebhookSecret:
type: string
no_echo: true
resources:
Inbound:
type: webhook
properties:
url: https://example.com/hooks/naturali
events: [messages.received]
secret:
param: WebhookSecret

Each property declares the whole value: dropping description from the template clears it, and an omitted active is true.

The deployer is held to the read action of every event type events selects, as a narrowed key is on a POST (who may register one). Missing any, the resource fails with ACTION_NOT_HELD, naming the action and resource.

secret is yours because a deploy returns no resource body, so a generated one would reach nobody (choosing the secret yourself). Configure your receiver with it before deploying. It is write-only: never stored in the resource ledger, never read back, re-sent on every update. Change the parameter to rotate it.

Examples​

Register an endpoint​

naturali create-webhook \
--project-id proj_V1StGXR8Z5jdHi6B \
--url https://example.com/hooks/naturali \
--events generations.* \
--events messages.received \
--description "billing service"

Audit what was delivered​

naturali list-webhook-deliveries \
--project-id proj_V1StGXR8Z5jdHi6B \
--webhook-id whk_V1StGXR8Z5jdHi6B \
--status failed

naturali get-webhook-delivery \
--project-id proj_V1StGXR8Z5jdHi6B \
--delivery-id whd_V1StGXR8Z5jdHi6B

Replay a failed delivery​

naturali redeliver-webhook-delivery \
--project-id proj_V1StGXR8Z5jdHi6B \
--delivery-id whd_V1StGXR8Z5jdHi6B

Pause an endpoint, then rotate its secret​

naturali update-webhook \
--project-id proj_V1StGXR8Z5jdHi6B \
--webhook-id whk_V1StGXR8Z5jdHi6B \
--active false

naturali rotate-webhook-secret \
--project-id proj_V1StGXR8Z5jdHi6B \
--webhook-id whk_V1StGXR8Z5jdHi6B