Webhook payload reference

Events

Event	Sent when	Retried?
`article.published`	An article is published to this webhook for the first time (or again after an unpublish).	Yes — up to 3 attempts
`article.updated`	You Re-publish an article published to this webhook.	Yes — up to 3 attempts
`article.updated`	You edit an article that is already published, to any destination.	No
`article.unpublished`	You Unpublish an article published to this webhook.	Yes — up to 3 attempts
`article.deleted`	You delete an article that is published, to any destination.	No
`test`	You choose Send test in the Webhook card’s ⋮ menu.	No

Every payload has the same shape, so one handler covers them all — branch on event.

For article.published, article.updated (from Re-publish) and article.unpublished, we wait for your answer. Anything other than a 2xx within 15 seconds fails the attempt; after three failed attempts (exponential backoff from 5 seconds) the publish, re-publish or unpublish fails, and the article keeps its previous state in SeoSorted. Answer 2xx only once you’ve stored — or removed — the post.article.unpublished still carries the publishedAt and publishedUrl of the post being removed, so you can match it against what you stored at publish time.

Headers

POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-SeoSorted-Signature: t=1786526112,v1=99ac6341579c16973ca9d1ecda22aa95cfabae850ab510c08a8c0fad4ae9f469
X-SeoSorted-Event: article.published
X-SeoSorted-Delivery: cmspviqsp0003ura62z7x7oj3

X-SeoSorted-Delivery is unique per attempt, so a retry of the same event arrives with a new value. It is useful for logging, but it is not an idempotency key — deduplicate on article.id + event. See verifying the signature.

Body

A real delivery, with the body fields truncated:

{
  "event": "article.published",
  "deliveredAt": "2026-08-12T09:39:43.035Z",
  "deliveryId": "cmspwe9fg0001urtydkeyx4k8",
  "workspace": {
    "id": "cmspuvypx0001urym6octbz30",
    "name": "seosorted.ai",
    "websiteUrl": "https://seosorted.ai"
  },
  "article": {
    "id": "cmspuvyq60005urymrk9q2mgk",
    "title": "How to Test a CMS Connector End to End",
    "slug": "how-to-test-a-cms-connector-end-to-end",
    "contentType": "BLOG_POST",
    "metaTitle": "How to Test a CMS Connector End to End",
    "metaDescription": "A practical walkthrough of verifying your publishing connector…",
    "focusKeyword": "cms connector",
    "featuredImageUrl": null,
    "targetLength": 1200,
    "wordCount": 125,
    "seoScore": 82,
    "publishedAt": "2026-08-12T09:00:32.276Z",
    "publishedUrl": null,
    "body": {
      "markdown": "## Why connector testing matters\n\nPublishing is the last mile…",
      "html": "<h2>Why connector testing matters</h2>\n<p>Publishing is the last mile…"
    }
  }
}

Fields

string

required

One of article.published, article.updated, article.unpublished, article.deleted, test.

string

required

ISO 8601 timestamp of when we built the payload.

string

required

Matches the X-SeoSorted-Delivery header. New on every attempt, including retries.

object

required

Show properties

string

Workspace id.

string

Workspace name, usually your domain.

string

The site this workspace tracks.

object

required

Show properties

string

Stable article id — use it to upsert on your side.

string

Article title.

string | null

URL slug we generated.

string

BLOG_POST, LISTICLE, GUIDE, and so on.

string | null

SEO title.

string | null

SEO description.

string | null

Primary keyword.

string | null

Hosted image URL — download it if you need a local copy.

number

Word count the article was written to.

number

Actual word count.

number | null

0–100 internal SEO score.

string | null

ISO timestamp of the first publish, if any. On article.unpublished this is still set — it describes the post you are being asked to remove.

string | null

Public URL, when a destination returned one — including on article.unpublished. For webhook articles, this is the publishedUrl, url, link or permalink your endpoint answered with; null if it never answered with one.

string | null

Article body as Markdown.

string | null

The same body rendered to HTML.

Take body.markdown if you store Markdown, body.html if you render directly. They are the same content — the HTML is rendered from the Markdown at delivery time.

A minimal handler

Upsert and delete by article.id, so a retried or repeated event is harmless, and reply with the live URL so SeoSorted can link to it. verify is the function from the webhook page; posts stands in for your own storage.

Express

import express from "express";
import { verify } from "./verify";
import { posts } from "./posts";

const app = express();

app.post("/seosorted/articles", express.raw({ type: "application/json" }), async (req, res) => {
  const signature = req.header("X-SeoSorted-Signature") ?? "";
  if (!verify(process.env.SEOSORTED_WEBHOOK_SECRET!, req.body.toString("utf8"), signature)) {
    return res.status(401).json({ error: "bad signature" });
  }

  const { event, article } = JSON.parse(req.body.toString("utf8"));

  switch (event) {
    case "article.published":
    case "article.updated": {
      await posts.upsert(article.id, article);
      return res.status(200).json({ url: `https://yoursite.com/blog/${article.slug}` });
    }
    case "article.unpublished":
    case "article.deleted":
      await posts.remove(article.id);
      return res.status(200).end();
    default:
      return res.status(200).end();
  }
});

Keep the work inside the 15-second timeout. If storing a post can take longer, queue it, but only for article.deleted and edit-time article.updated events — for publish, re-publish and unpublish, your 2xx is what tells SeoSorted the change landed.

Get started

Publishing destinations

Analytics sources

Reference

Events

Headers

Body

Fields

A minimal handler

​Events

​Headers

​Body

​Fields

​A minimal handler

Events

Headers

Body

Fields

A minimal handler