Webhooks

Setting one up

Add a webhook under Settings in the dashboard: a URL, the events you want, and an active toggle. Sedgemark generates a signing secret for you.

• HTTPS only. An http:// URL is rejected when you save it.
• Public addresses only. Loopback, link-local and private ranges are refused, so a webhook cannot be pointed at infrastructure that is not reachable from the internet. This also means you cannot deliver to a local listener during development , so use a tunneling service that gives you a public HTTPS hostname.
• The secret is stored encrypted and decrypted only at delivery time. Managing webhooks is an owner-level action.

What arrives

Every delivery is a POST with the same three-key envelope, whatever the event:

POST https://your-endpoint.example.com/sedgemark
Content-Type: application/json
X-Sedgemark-Signature: sha256=6d2f8b1c…

{
  "event": "content.published",
  "data": { /* varies by event, see below */ },
  "timestamp": "2026-08-04T15:04:05.000Z"
}

Events

Content events

entry is the stored row, including all the system columns.

{
  "event": "content.published",
  "data": {
    "collection": "blog_post",
    "entry": {
      "id": "9f8c1a2b-4d5e-4f60-8a71-2c3d4e5f6071",
      "title": "Hello, world",
      "body": "<p>My first post.</p>",
      "_status": "published",
      "_published_at": "2026-08-04T15:04:05.000Z",
      "_created_by": "3b1e7c40-88a2-4d19-9f5c-6a0b1d2e3f40",
      "_created_at": "2026-08-04T14:58:11.000Z",
      "_updated_at": "2026-08-04T15:04:05.000Z"
    }
  },
  "timestamp": "2026-08-04T15:04:05.000Z"
}

Note that content.deleted and content.unpublished also carry the whole entry, not just an id. For a deletion that is the only remaining record of what was removed.

Form submissions

{
  "event": "form.submitted",
  "data": {
    "form": {
      "id": "c14f2e70-9a3b-4c5d-8e6f-0a1b2c3d4e5f",
      "slug": "contact",
      "name": "Contact us"
    },
    "formId": "c14f2e70-9a3b-4c5d-8e6f-0a1b2c3d4e5f",
    "submission": {
      "id": "5a1f3c88-2b47-4e19-90d6-7c8e9f0a1b2c",
      "_submitted_at": "2026-08-04T15:04:05.000Z"
    }
  },
  "timestamp": "2026-08-04T15:04:05.000Z"
}

formId duplicates form.id. Both are sent; prefer form.slug for routing, since it is the name you gave the form and the one that appears in its URL.

Verifying the signature

Every delivery carries an X-Sedgemark-Signature header: the string sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your webhook’s secret.

Your endpoint is a public URL, so anyone can POST to it. Verify every request before acting on it, and reject anything that fails.

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

const SECRET = process.env.SEDGEMARK_WEBHOOK_SECRET

export function verify(rawBody, signatureHeader) {
  // Compute over the RAW body bytes, exactly as received. Parsing to an object
  // and re-stringifying reorders and reformats it, and the signature will not
  // match.
  const expected = 'sha256=' + createHmac('sha256', SECRET).update(rawBody).digest('hex')

  const a = Buffer.from(expected)
  const b = Buffer.from(signatureHeader ?? '')

  // timingSafeEqual throws on a length mismatch, so check that first.
  return a.length === b.length && timingSafeEqual(a, b)
}

import express from 'express'

const app = express()

// express.raw, not express.json: the verifier needs the untouched bytes.
app.post('/sedgemark', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('X-Sedgemark-Signature'))) {
    return res.sendStatus(401)
  }

  const { event, data, timestamp } = JSON.parse(req.body.toString('utf8'))

  // Acknowledge immediately; do the work afterwards. Sedgemark gives up on a
  // response after 10 seconds and retries.
  res.sendStatus(200)

  void handle(event, data, timestamp)
})

Custom headers

A webhook can carry up to 10 custom name/value pairs, sent on every delivery, most often an Authorization header for a receiver that expects one, like GitHub’s repository_dispatch API below.

POST /api/dashboard/webhooks
Content-Type: application/json

{
  "url": "https://api.github.com/repos/acme/site/dispatches",
  "events": ["content.published", "content.unpublished"],
  "format": "github_repository_dispatch",
  "headers": {
    "Authorization": "Bearer ghp_your_pat_here",
    "Accept": "application/vnd.github+json"
  }
}

• Stored encrypted, read back as names only. A GET or a PUT response never includes header values, only a sorted header_names array, the same shape the webhook’s secret already follows. There is no endpoint that returns a value you set once you have set it.
• A fixed set of names is refused. Host, Content-Type, Content-Length, Transfer-Encoding, Connection and X-Sedgemark-Signature (case-insensitively) can never be set as a custom header, since the dispatcher sets every one of them itself on every delivery and a custom header is never allowed to override them.
• Names must be a legal HTTP header token; values are capped at 1024 characters and may not contain control characters, including a raw CR or LF, which are rejected outright rather than stripped.

{
  "id": "c14f2e70-9a3b-4c5d-8e6f-0a1b2c3d4e5f",
  "url": "https://api.github.com/repos/acme/site/dispatches",
  "events": ["content.published", "content.unpublished"],
  "active": true,
  "format": "github_repository_dispatch",
  "header_names": ["Accept", "Authorization"],
  "created_at": "2026-08-04T14:58:11.000Z"
}

Payload format

A webhook’s optional format changes the shape of the delivered body, never which events it fires for; that is still events. There are 2:

github_repository_dispatch exists because GitHub’s POST /repos/{owner}/{repo}/dispatches rejects any body missing an event_type key with a 422, and caps client_payload at 10 top-level properties. The full entry payload would not fit and would not be accepted anyway, so this format sends a small, fixed shape instead of the whole entry:

{
  "event_type": "sedgemark.content.published",
  "client_payload": {
    "event": "content.published",
    "collection": "blog_post",
    "entryId": "9f8c1a2b-4d5e-4f60-8a71-2c3d4e5f6071",
    "timestamp": "2026-08-04T15:04:05.000Z"
  }
}

X-Sedgemark-Signature is still computed and sent, over this reshaped body; verification works exactly the same as for the default format.

This is one half of triggering a CI rebuild from published content. The full recipe (the GitHub PAT’s scope, the Actions workflow, and where sedgemark deploy fits) is Auto-rebuild on publish.

Operating a webhook

Delivery behavior

Debouncing

Someone editing an entry in the dashboard generates a burst of saves. Two mechanisms collapse those into one delivery.

• Always on: content.updated events for the same entry within half a second are coalesced into a single delivery carrying the latest state. No other event is affected, and there is nothing to configure.
• Optional, per webhook: set a debounce_ms of up to one hour. Sedgemark then waits that long after the last matching event before delivering. A debounce_scope of entry collapses per entry; webhook collapses everything for that webhook and event into one delivery, which is what you want for a “rebuild the site” hook, where fifty changes should cause one build.

Both are configured in the dashboard, not over an API. They stack only where they overlap: for content.updated, a webhook with a debounce set sees an effective delay of roughly that value plus the half-second coalescing window. Every other event skips the coalescing step entirely, so its delay is exactly the value you set.

Common setups