Webhooks

​

Create a webhook

curl -X POST "https://api.nohead.io/v1/projects/$PROJECT_ID/webhooks" \
  -H "Authorization: Bearer $NOHEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/nohead",
    "event_types": ["record.published", "record.unpublished"],
    "description": "Rebuild the website"
  }'

const webhook = await nohead.webhooks.create({
  url: "https://example.com/webhooks/nohead",
  event_types: ["record.published", "record.unpublished"],
  description: "Rebuild the website",
})
console.log(webhook.secret) // whsec_…, shown only now

webhook = nohead.webhooks.create(
    url="https://example.com/webhooks/nohead",
    event_types=["record.published", "record.unpublished"],
    description="Rebuild the website",
)
print(webhook.secret)  # whsec_..., shown only now

webhook = nohead.webhooks.create(
  url: "https://example.com/webhooks/nohead",
  event_types: ["record.published", "record.unpublished"],
  description: "Rebuild the website"
)
puts webhook.secret # whsec_..., shown only now

​

Event types

​

Published content only

• Record events when the record was published before or after the change: publishing, unpublishing, editing a live record (or merging a draft into it), and deleting or restoring a published record. Edits to unpublished records are skipped.
• Every collection and field event, since published-only keys read the schema.
• Asset events for assets that published records use. A new upload is skipped until a published record uses it.

const webhook = await nohead.webhooks.create({
  url: "https://example.com/deploy-hook",
  event_types: ["record.*", "asset.*"],
  published_only: true,
  description: "Rebuild the website",
})

webhook = nohead.webhooks.create(
    url="https://example.com/deploy-hook",
    event_types=["record.*", "asset.*"],
    published_only=True,
    description="Rebuild the website",
)

webhook = nohead.webhooks.create(
  url: "https://example.com/deploy-hook",
  event_types: ["record.*", "asset.*"],
  published_only: true,
  description: "Rebuild the website"
)

​

The payload

{
  "id": "evt_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "event",
  "type": "record.published",
  "created_at": "2026-10-22T09:30:00.000Z",
  "project_id": "prj_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "actor": { "type": "api_key", "id": "key_01J9ZQ3F8X5W2K7M4N6P0R1S2T", "name": "Importer" },
  "via": "sdk",
  "data": {
    "record": { "id": "rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T", "object": "record", "collection": "blog-posts", "revision": 4, "data": { "title": "Hello" } },
    "revision": 4,
    "revision_id": "rev_01J9ZQ3F8X5W2K7M4N6P0R1S2T"
  }
}

• actor is who made the change (a user, an API key, or the system), and via the client it came through (ui, api, cli, sdk, mcp, system or scheduler). An integration that writes back can skip changes made with its own API key.
• Record events carry the record as the change left it, with the revision it made and the revision’s ID. Events without a revision (record.scheduled, record.unscheduled, record.schedule_failed, record.redacted) carry the record as it is now. Once a record is purged, every event about it has record: null.
• Draft events carry the draft as it is now (null once merged or discarded), collection and field events the collection and the schema change, and asset events the asset (only its id once it is purged, as in asset.purged).

​

Delivery

• Success is any 2xx response within 10 seconds. Any other status, a timeout or a connection error is a failed attempt. Redirects aren’t followed, so a 3xx fails too.
• Retries follow a failed attempt after 5 seconds, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 10 hours. After 8 attempts, about a day, the delivery fails.
• At least once. The same event can arrive more than once, for example when your endpoint was slow to answer. Deduplicate by webhook-id, which stays the same on every attempt.
• No ordering. A retried event can arrive after later ones. Compare created_at, or a record’s revision, to tell which change is newer.

​

Delivery history and retries

const webhookId = "wh_01J9ZQ3F8X5W2K7M4N6P0R1S2T"
for await (const delivery of nohead.webhooks.deliveries.list(webhookId, { status: "failed" })) {
  await nohead.webhooks.deliveries.retry(delivery.id)
}

webhook_id = "wh_01J9ZQ3F8X5W2K7M4N6P0R1S2T"
for delivery in nohead.webhooks.deliveries.list(webhook_id, status="failed"):
    nohead.webhooks.deliveries.retry(delivery.id)

webhook_id = "wh_01J9ZQ3F8X5W2K7M4N6P0R1S2T"
nohead.webhooks.deliveries.list(webhook_id, status: "failed").each do |delivery|
  nohead.webhooks.deliveries.retry(delivery.id)
end

​

Disabling and deleting

​

Verify signatures

1. Build the signed string: {webhook-id}.{webhook-timestamp}.{raw body}.
2. Compute its HMAC-SHA256, keyed with the base64-decoded part of your secret after whsec_, and base64-encode it.
3. webhook-signature holds one or more space-separated signatures, each v1,<base64>. Accept the request if any of them equals yours, compared in constant time.
4. Reject the request if webhook-timestamp (Unix seconds, new on each attempt) is more than five minutes from your clock.

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

// headers: lowercase names, as Node gives them. body: the raw body, as a string.
export function verifyNoheadWebhook(secret, headers, body) {
  const id = headers["webhook-id"]
  const timestamp = headers["webhook-timestamp"]
  const signatures = headers["webhook-signature"]
  if (!id || !timestamp || !signatures) return false
  const age = Math.abs(Date.now() / 1000 - Number(timestamp))
  if (!(age <= 300)) return false

  const key = Buffer.from(secret.slice("whsec_".length), "base64")
  const digest = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64")
  const expected = Buffer.from(`v1,${digest}`)
  return signatures.split(" ").some((signature) => {
    const given = Buffer.from(signature)
    return given.length === expected.length && timingSafeEqual(given, expected)
  })
}

​

Rotate the secret