Webhook

Send every published article to your own HTTP endpoint, signed so you can verify it came from us.

The webhook connector POSTs a JSON payload to a URL you control whenever an article is published. Use it for a headless CMS, a static site generator, an internal review queue, or any CMS we don’t support natively.

Step 1 — Have an endpoint ready

You need a URL that accepts POST with a JSON body and answers with a 2xx status. Anything outside 200–299 counts as a failed delivery.

The endpoint must be reachable from the public internet. localhost works only while you are testing against a local SeoSorted install.

Step 2 — Connect

Project Settings → Integrations → Webhook → Connect.

The webhook connect form

Endpoint URL · string · required

Where we POST, for example https://api.yourapp.com/seosorted/articles.

Signing secret · string

Optional. At least 16 characters. Leave it blank and we generate one for you — the usual choice.

Description · string

Optional label for your own reference, e.g. “Production blog publisher”.

A secret shorter than 16 characters is rejected before anything is saved:

Short secrets are caught up front

Step 3 — Save the signing secret

If we generated the secret, it is shown once, immediately after connecting.

Copy the signing secret — it is shown once

Store it in your app’s secret manager before clicking Done. We keep it encrypted and cannot show it again. Lost it? Reconnect the webhook to generate a new one, then update your endpoint.

Step 4 — Send a test delivery

The connected card has a Send test button. It posts a test event with a realistic payload and tells you exactly what your endpoint replied.

Send test posts a sample payload and reports the response

You’ll see one of:

Result	Meaning
Test delivered — your endpoint replied 200 in 7ms.	Working.
Test failed: your endpoint replied 500	Reached your server; it errored. Check your logs.
Test failed: Connection refused by host — nothing is listening…	Wrong port, or the service is down.
Test failed: DNS lookup failed for host	The hostname doesn’t resolve publicly.
Test failed: No response from host within 15s	Answer faster — queue the work and reply immediately.

Step 5 — Publish

Publish an article and choose Webhook. Because a webhook has no public URL to link to, success is confirmed in place.

A webhook publish confirms delivery

Verifying the signature

Every request carries these headers:

Header	Example
X-SeoSorted-Signature	t=1786526112,v1=99ac6341579c…
X-SeoSorted-Event	article.published
X-SeoSorted-Delivery	cmspviqsp0003ura62z7x7oj3

The signature is an HMAC-SHA256 of <t>.<raw request body> keyed with your signing secret, where t is the Unix timestamp in the same header.

Node.js

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

const TOLERANCE_S = 5 * 60;

export function verify(secret: string, rawBody: string, header: string): boolean {
  const parts = Object.fromEntries(
    header.split(",").map((p) => {
      const [k, ...rest] = p.trim().split("=");
      return [k, rest.join("=")];
    }),
  );
  if (!parts.t || !parts.v1) return false;

  // Reject replays of an old, previously valid request.
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > TOLERANCE_S) return false;

  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  return timingSafeEqual(Buffer.from(parts.v1, "hex"), Buffer.from(expected, "hex"));
}

Compute the HMAC over the raw request body, before any JSON parsing. Re-serializing the parsed object changes the bytes and the signature will never match.

Delivery behaviour

• Timeout: 15 seconds. Reply quickly and do the slow work asynchronously.
• Retries: deliveries are attempted once. A failure is recorded with the response status, body and error so you can see what happened.
• Health: after 5 failed deliveries within an hour, the connector is marked Error on the Integrations tab.
• Duplicates: use X-SeoSorted-Delivery as an idempotency key.

See the payload reference for the exact JSON body.