Coding agent documentation index Fetch the complete documentation index at: https://docs.worklittle.com/docs-agent-manifest.json Use this file to discover all available pages before exploring further.

Webhooks reliability

Verify signatures, dedupe at-least-once deliveries, acknowledge fast, and reconcile.

How delivery works

Worklittle POSTs JSON to your endpoint and records each attempt in the delivery log. Failed deliveries retry with backoff.

{
  "id": "wh_…",
  "type": "candidate.application_submitted",
  "created_at": 1748948400,
  "data": { }
}

created_at is Unix seconds. Subscribe to "*" or specific types. Manage endpoints with /webhooks or MCP list_webhooks, create_webhook, update_webhook, rotate_webhook_secret, test_webhook, list_webhook_deliveries. Event list: Webhooks.

Verify before you trust

| Header | Purpose |
| --- | --- |
| `Worklittle-Webhook-Id` | Unique delivery id. Dedupe key |
| `Worklittle-Webhook-Timestamp` | Unix timestamp. Reject replays |
| `Worklittle-Webhook-Signature` | `v1=<hmac>` over `timestamp.body` |

import crypto from "node:crypto";

function verify(sigHeader, timestamp, rawBody, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = sigHeader.replace(/^v1=/, "");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
}

Verify against the raw body before parsing JSON. Reject old timestamps. When you rotate with rotate_webhook_secret, accept both secrets during rollover.

Idempotency

Delivery is at-least-once and unordered.

Dedupe on Worklittle-Webhook-Id with a unique constraint and retention that covers the retry window. On conflict, return 200 and stop. Make writes idempotent. Upsert on a stable business id. "Set stage to onsite" is idempotent. "Advance one stage" is not. Derive downstream idempotency keys from the delivery id. Handle out-of-order events. Discard an update whose created_at is older than the state you hold.

Acknowledge fast, work async

Return 2xx once the payload is verified and durably queued. Do real work in a background worker. Slow handlers time out, trigger retries, and repeat the work. Keep the path to verification, dedupe insert, enqueue, and return well under a second.

Reconciliation

Webhooks give latency. Reconciliation gives correctness.

Hourly, list records changed since your watermark and compare with your mirror. Keep it narrow and paginated. Use list_webhook_deliveries to inspect attempts. Use test_webhook after changing your handler, TLS, or firewall. * For careers-site caches, revalidate on job.published, job.updated, job.closed and keep a slow background refresh.