Signed delivery | incld docs

Request contract

Header	Meaning
Content-Type	application/json
Incld-Signature	t=<unix seconds>,v1=<lowercase HMAC-SHA256 hex>
Incld-Idempotency-Key	Stable delivery identity; present for scheduled runs and Bulk chunks

Event envelope json

{
 "id": "evt_...",
 "type": "run.created",
 "created_at": "2026-08-21T01:30:00Z",
 "data": {}
}

Current executable event types are run.created and bulk.chunk. The framework integration turns them into declared action handler input and rejects any identifier not present in your server registry.

Signature verification

01

Read the raw bytes

Do not parse and re-encode JSON before verification.
02

Parse the header

Extract the integer t value and hexadecimal v1 value.
03

Enforce freshness

Reject timestamps outside the default 300-second tolerance.
04

Compute the digest

HMAC-SHA256 the exact string <timestamp>.<raw body> using the project webhook secret.
05

Compare safely

Use constant-time comparison, then decode and dispatch the event.

Manual JavaScript verification ts

import { verifyWebhookSignature } from "@incld/client"

const valid = await verifyWebhookSignature(
 rawBody,
 signature,
 process.env.INCLD_WEBHOOK_SECRET!,
 300,
)

if (!valid) throw new Error("Invalid incld signature")
const event = JSON.parse(rawBody)

The JavaScript verifier returns a boolean; it does not parse JSON. Keep the exact raw string until verification succeeds, then decode it. Framework adapters perform both steps for you.

Delivery payloads

Event	Important data
run.created	data.run includes run and schedule identity, action metadata, payload snapshot, nominal time, and revision
bulk.chunk	data.operation includes id, action, metadata; data.chunk includes id, index, and items

Framework action handlers receive normalized action, payload, event, request, and authenticated client values. Bulk payloads additionally normalize operationId, chunkId, chunkIndex, items, and metadata.

Responses, retries, and idempotency

Response	Behavior
2xx	Delivery accepted; the handler should only return after durable application work is committed.
Non-2xx	Delivery fails and is retried according to the component policy.
Timeout/network error	Delivery is treated as failed and may be retried.
Duplicate idempotency key	Return the previously committed outcome without repeating side effects.

Current backoff intervals are 30 seconds, 2 minutes, 10 minutes, 1 hour, and 6 hours. Bulk chunks make at most six attempts. Scheduled deliveries use the same signed transport and stable run identity.

Keep proxy and webhook routes separate

The browser proxy resolves your logged-in user and forwards allowed REST operations. The webhook route verifies Incld-Signature and executes server actions. Never expose either project secret to browser code.