Webhooks

Adding an endpoint

On the dashboard, open a project’s Settings → Notifications. Give the address and tick the events you want. Tick none to receive every event, including events added later. You need to be allowed to change the project’s settings.

With the API, POST /api/v1/projects/{project}/webhooks with {"url": "https://…", "events": ["draft.published"]}. The names a list may hold are in the catalogue below, and GET /api/v1/webhook-events answers the same list with each payload’s JSON Schema. A name that is not an event is refused.

• The address must use HTTPS and be reachable from the public internet.
• The answer carries the signing secret, once. Store it then: it is never shown again. An endpoint an assistant added shows its secret once on the dashboard instead, so it never reaches a conversation.
• Each endpoint has its own secret. Add a separate endpoint per project, even when they share an address: every delivery names its project in project_id.

What a delivery looks like

A POST with a JSON body and three headers that identify and sign it:

POST /hooks/webentor HTTP/1.1
content-type: application/json
user-agent: Webentor-Cloud-Webhooks/1
webhook-id: msg_0196f2c4-7a10-7c3e-9a51-3f2a0d9b8e41
webhook-timestamp: 1763035200
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

• webhook-id is the message’s id. It is the same on every attempt and on a redelivery, so keep it to recognise a message you have already handled.
• webhook-timestamp is when this attempt was sent, in seconds since 1970. When the event happened is timestamp in the body.
• webhook-signature is one signature, v1, and base64, or two separated by a space for 24 hours after the secret was rotated.

The body is the same envelope for every event:

{
  "id": "msg_0196f2c4-7a10-7c3e-9a51-3f2a0d9b8e41",
  "type": "draft.published",
  "timestamp": "2026-11-13T12:00:00.000Z",
  "version": 1,
  "account_id": "0196a1b2-0000-7000-8000-000000000001",
  "project_id": "0196a1b2-0000-7000-8000-000000000002",
  "data": {
    "draft_id": "0196f2c4-0000-7000-8000-000000000003",
    "commit": "4f0c2e9…",
    "pages": 3,
    "hidden_pages": 0
  }
}

Fields are only ever added, to the envelope and to an event’s data. Read the fields you need and ignore the rest; a receiver that refuses unknown fields breaks on the next one. version changes only for a change that is not additive.

A payload carries ids and a few values, never content: no page text, no comment, nothing a visitor typed into a form, no email address. Read what you need with the API and your own token.

Verifying a signature

Check every delivery before you act on it. Anybody can send a request to your address; only we can sign one with your secret. In any language:

1. Take the body exactly as it arrived, as text. Parsing the JSON and writing it out again changes the bytes, and the signature no longer matches.
2. Refuse the request when webhook-timestamp is more than five minutes from your clock. That stops somebody replaying an old delivery.
3. Take the secret without its whsec_ prefix and decode it from base64. That is the key.
4. Compute HMAC-SHA256 with that key over the id, a full stop, the timestamp, a full stop and the body: {webhook-id}.{webhook-timestamp}.{body}.
5. Split webhook-signature on spaces. The delivery is genuine when one entry is v1, followed by your result in base64. Compare in constant time.

In Node, with nothing but its own crypto module:

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

// secret:  the endpoint's signing secret, as it was shown to you (whsec_...).
// headers: the request's headers, with lower-case names.
// body:    the raw request body as a string, before any JSON parsing.
export function verifyWebhook(secret, headers, body) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures) throw new Error('Missing webhook headers');

  // Refuse a replay: the timestamp is when this attempt was sent.
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (!(age <= 5 * 60)) throw new Error('Timestamp outside the tolerance');

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest();

  // One signature, or two for a day after the secret was rotated.
  for (const candidate of signatures.split(' ')) {
    const [version, signature] = candidate.split(',');
    const given = Buffer.from(signature ?? '', 'base64');
    if (version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected)) {
      return JSON.parse(body);
    }
  }
  throw new Error('No matching signature');
}

The Standard Webhooks libraries do the same in many languages; pass them the secret and the raw body. A secret made before 13 November 2026 may hold - or _, which the code above reads and a strict library refuses. Rotate it for a new one, or decode it as base64url: the key is the same.

Retries, duplicates and the delivery log

• A delivery succeeds when your endpoint answers with a 2xx status within ten seconds. Anything else is a failure: another status, no answer, a connection that fails. A redirect is not followed; change the endpoint to the address it redirects to.
• A failed delivery is tried again, waiting longer each time (30 seconds, 60 seconds, 2 minutes, 4 minutes, 8 minutes, 16 minutes, 32 minutes, 60 minutes, then every hour), for a day after the first attempt. Then it is given up and shown as failed. Each endpoint is tried by itself: one that fails does not hold up or repeat the others.
• The same message can arrive more than once, after a retry whose answer was lost or a redelivery. Keep the webhook-id values you have handled and skip one you have seen.
• Messages are not in order. Use timestamp to order events, and read the current state with the API when order matters.
• Answer quickly and do the work afterwards. A slow answer is a timeout, and a timeout is a retry.

Each endpoint keeps a log of what it was sent and what it answered, for 30 days: the status code, how long it took, and why a delivery failed. It is under the endpoint on the dashboard, and at GET /api/v1/projects/{project}/webhooks/{id}/deliveries. From there you can send a delivery again, and send a webhook.test event to try an endpoint without anything happening in the project.

An endpoint that has done nothing but fail for 3 days is switched off, and the people who manage the project’s settings are told. So is one that answers 410 Gone, at once. Nothing is sent to it until somebody switches it on again; what it missed can be sent again from its log.

To change the secret, rotate it. The old one keeps signing beside the new one for 24 hours, so the receiving end can switch without missing a delivery.

Events

Every event, with its payload, the fields of data. The date is the day it was first sent. New events are added here, and endpoints with no event list start receiving them. deploy.held belongs with the deployment.* events despite its prefix.

• project.created
• draft.created
• draft.submitted
• draft.approved
• draft.changes_requested
• review.comment_added
• draft.scheduled
• draft.merged
• draft.discarded
• draft.published
• draft.schedule_failed
• code.published
• import.finished
• build.succeeded
• build.failed
• deploy.held
• deployment.production
• deployment.failed
• deployment.rolled_back
• domain.verified
• domain.failed
• export.finished
• project.deletion_scheduled

project.created

A project was created. A new project finished provisioning: its repository exists and it can be edited. Sent at the end of provisioning, not when it was asked for.

Since 2026-08-28

draft.created

A draft was started. A draft was opened on the project, by a person, an assistant, a push, a fork, an import, a rollback or an upgrade. `origin` says which.

Since 2026-08-28

draft.submitted

A draft was sent for review. Somebody asked for a decision on a draft. `purpose` says which: `review` asks for a review, `publish` asks a person with the right to publish it.

Since 2026-08-28

draft.approved

A draft was approved. A reviewer approved a draft that was sent for review. The approval is of the version they read; a later save drops it. Not the reviewer’s note: read the draft’s comments with the API.

Since 2026-11-13

draft.changes_requested

Changes were asked for on a draft. A reviewer sent a draft back for changes. Not the reviewer’s note: read the draft’s comments with the API.

Since 2026-11-13

review.comment_added

Somebody commented on a draft. A comment was added to a draft’s review. Never the comment’s text: read it with the API.

Since 2026-11-13

draft.scheduled

A draft was scheduled to go live. Somebody chose a time for a draft to be published. If it cannot go live then, `draft.schedule_failed` follows; if it can, `draft.published`.

Since 2026-11-13

draft.merged

A draft was merged into another line. A draft’s changes were merged, into another line or into the live branch by the merge route. A publish is `draft.published`.

Since 2026-11-13

draft.discarded

A draft was discarded. A draft was closed without being published. Its branch is archived in the repository, not deleted.

Since 2026-11-13

draft.published

A draft went live. A draft was merged into the live branch. The production build and deployment follow; `deployment.production` says when visitors see it.

Since 2026-08-28

draft.schedule_failed

A scheduled publish did not happen. A draft was scheduled to go live at a time, and could not. The schedule is cleared and the site is unchanged.

Since 2026-09-11

code.published

Code was pushed to the live branch. A Git push moved the live branch and a production build was queued for it.

Since 2026-08-28

import.finished

A site import finished. An import of an existing site ended. `status` says how; the imported pages are on the draft named here.

Since 2026-08-28

build.succeeded

A build succeeded. A build finished without an error. Sent for every kind of build, not only the ones that go live: read `trigger` to tell them apart.

Since 2026-08-28

build.failed

A build failed. A build ended with an error. Sent for every kind of build: read `trigger` to tell them apart.

Since 2026-08-28

deploy.held

A deployment was held back. A production build finished and was not deployed, for the reason given. The live site still serves the previous version. Part of the `deployment.*` family despite its prefix.

Since 2026-11-11

deployment.production

A deployment went live. A production deployment succeeded: visitors now see this build. A rollback is one too, marked `rollback: true`, after its own `deployment.rolled_back`.

Since 2026-08-28

deployment.failed

A deployment failed. A production deployment did not succeed: the provider refused it, or it failed before the provider answered. The live site still serves the previous version unless `site_changed` says otherwise.

Since 2026-08-28

deployment.rolled_back

The live site was rolled back. Somebody put an earlier version back. Its deployments follow as `deployment.production` with `rollback: true`, and a revert draft is opened to carry the change into the live branch.

Since 2026-11-13

domain.verified

A domain started working. A domain’s DNS records checked out and it serves the project. Sent on the change only, not each time a working domain is checked again.

Since 2026-11-13

domain.failed

A domain stopped working. A domain that had been working stopped verifying: visitors on that hostname may not reach the site. Sent on the change only.

Since 2026-11-13

export.finished

An export finished. An export bundle of the project was made, or could not be. No download address: fetch it with the API and your own token.

Since 2026-11-13

project.deletion_scheduled

A project was scheduled for deletion. The project was taken offline to be erased on `purge_after`, unless somebody restores it before then. Nothing is sent after it is erased: its endpoints go with it.

Since 2026-11-13