Any site can receive articles from Sei, and hand its own articles to Sei for import, through one HTTPS endpoint that accepts Sei's signed webhooks. This page is the whole contract. Two packages implement it:
@getsei/webhook(packages/webhook, MIT): verification and a ready request handler for any JavaScript server.@getsei/payload(packages/payload, MIT): a Payload CMS 3 plugin built on it.
Other languages need only an HMAC-SHA256 and a JSON parser: see "Verifying a request" below.
Transport
- Sei sends
POST <endpoint>withContent-Type: application/jsonand waits for the answer: there is no queue and no automatic retry. A publish that fails is reported to the person who clicked Publish. - The endpoint must be
https://(a private orlocalhostendpoint only works with a local Sei in development). - Sei waits 20 seconds for
pingandarticle.list, 40 seconds forarticle.publishandarticle.unpublish. - Sei reads at most 2 MB of the answer, and never follows a redirect: a
3xxis a failure. Enter the final URL.
Signing (Standard Webhooks)
Every request is signed as the Standard Webhooks spec describes, so any Standard Webhooks library verifies it. Headers:
| Header | Value |
|---|---|
webhook-id |
msg_ and 32 hex characters. New for every delivery, never containing a .. |
webhook-timestamp |
When Sei sent it: unix seconds. |
webhook-signature |
v1, and the base64 HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}. |
sei-protocol |
1. |
The signing secret is whsec_ followed by the base64 of 32 random bytes. Sei generates it (Settings → the site
→ Custom site → Generate secret), shows it once and keeps it encrypted. Rotate secret replaces it at once: the
old one stops working with the next request.
The webhook-signature header is a space-separated list. Today Sei sends one v1, signature; a receiver must try
each v1, entry and ignore other versions (v1a, is the asymmetric scheme).
Verifying a request
- Read the raw body exactly as it arrived, before any JSON parsing.
- Refuse the request if
webhook-id,webhook-timestamporwebhook-signatureis missing. - Refuse it if the timestamp is more than 5 minutes from your clock, either way (a replayed request is old).
- Take the key: the secret without
whsec_, base64-decoded. Compute HMAC-SHA256 over the UTF-8 bytes ofwebhook-id + "." + webhook-timestamp + "." + body, and base64 it. - Accept the request if any
v1,<signature>in the header equals it. Compare in constant time (crypto.timingSafeEqual,hmac.compare_digest,hash_equals). - Treat a
webhook-idyou have already seen as a duplicate (keep ids at least 10 minutes).@getsei/webhooktakes aseenhook for this; Sei never reuses an id, so a repeat is a replay.
The reference vector, from the Standard Webhooks library: secret whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw, id
msg_p5jXN8AQM9LWM0D4loKWxJek, timestamp 1614265330, body {"test": 2432232314} give
v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=.
Answer 401 when verification fails. Sei then marks the connection "needs attention".
Requests
The body is one JSON object: { "type": …, …fields }.
type |
Fields | Answer (200, JSON) |
|---|---|---|
ping |
siteId |
{ "ok": true, "protocol": 1, "capabilities": [...], "name"?, "timezone"? } |
article.publish |
article, mode, scheduledAt?, ifRevision?, seoOnly?, asNew? |
{ "externalId", "revision", "status", "hasPendingDraft"?, "url"? } |
article.unpublish |
externalId, ifRevision? |
{ "externalId", "revision", "status": "draft" } |
article.list |
limit (1–100), cursor? |
{ "items": [ExternalArticle…], "nextCursor"? } |
terms.list (1.1, optional) |
none | { "categories": [Term…], "tags": [Term…] } |
article.delete (1.2, optional) |
externalId |
{ "externalId", "recoverable": true | false } |
article.restore (1.2, optional) |
externalId |
{ "externalId", "revision", "status": "draft", "url"? } |
article.preview (1.4, optional) |
article |
{ "url" } |
ping is Settings → Test connection. capabilities lists what the receiver does: publish (required),
unpublish, list, drafts (it saves draft publishes), schedule (it schedules) and taxonomies (it stores
the categories and tags Sei sends; see below). Sei hides Import without list, and "Save as new draft" when the
answer leaves out drafts (until then it is offered).
With @getsei/webhook, onPing returns drafts, schedule and (for a receiver that stores terms without listing
them) taxonomies; the handlers given make the rest (onTerms adds taxonomies). name is shown in Sei ("Publish to My blog"); timezone
(an IANA name like Europe/Berlin, or an offset like +05:30) sets Sei's schedule picker.
{ "type": "ping", "siteId": "8b0d2c1e-5f00-4a51-9a7e-3c2f1d0e9b8a" }{ "ok": true, "protocol": 1, "capabilities": ["publish", "unpublish", "list", "drafts", "schedule"], "name": "My blog", "timezone": "Europe/Berlin" }article.publish creates or updates an article.
mode:publish(live now),draft(not public), orschedule(live atscheduledAt, ISO 8601). A receiver without drafts or scheduling answers422 { "code": "unsupported-mode" }.article.externalIdabsent: a create. Sei may retry a create whose answer it never got (a timeout): find the article you created for the samearticle.seiIdand update it instead of creating a second one.ifRevision: update only if the article is still at this revision (what your last answer calledrevision); otherwise answer409(below). Sei leaves it out when the person chose "Overwrite".seoOnly: true: the article has content Sei can't represent. Update onlyslug,seoTitle,metaDescriptionandkeyphrase: never the body, the title or the status.asNew: true: "Save as new draft" after a conflict. Create a new article even if one already has thisseiId; leave the original as it is.
{
"type": "article.publish",
"mode": "publish",
"ifRevision": "2026-10-19T09:00:00.000Z",
"article": {
"seiId": "4d8d1c2e-7c4b-4f43-a0d6-2b8b5f8d9e10",
"externalId": "17",
"title": "Pour-over coffee at home",
"slug": "pour-over-coffee",
"seoTitle": "Pour-over coffee at home | Harbor & Pine",
"metaDescription": "Brew a clean, bright cup in four minutes.",
"keyphrase": "pour-over coffee",
"author": "Maya Lindqvist",
"contentHtml": "<h2>Gear</h2>\n<p>A <strong>gooseneck</strong> kettle and a <a href=\"https://x.example/scale\">scale</a>.</p>",
"contentBlocks": {
"blocksVersion": 1,
"blocks": [
{ "type": "heading", "level": 2, "text": "Gear" },
{ "type": "paragraph", "text": "A gooseneck kettle and a scale.", "marks": [{ "type": "bold", "start": 2, "end": 11 }], "links": [{ "href": "https://x.example/scale", "start": 25, "end": 30 }] }
]
},
"scores": { "seo": 81, "readability": 72, "geo": 64 },
"updatedAt": "2026-10-19T09:30:00.000Z",
"featuredImage": { "url": "https://abc.public.blob.vercel-storage.com/articles/4d8d…/kettle-x1y2.jpg", "alt": "A gooseneck kettle on a scale" }
}
}{ "externalId": "17", "revision": "2026-10-19T09:30:02.114Z", "status": "published", "url": "https://blog.example/pour-over-coffee" }article.unpublish turns a published article back into a draft (same ifRevision rule). A receiver without
drafts answers 422 unsupported-mode; one without the capability answers 404 unsupported.
article.list pages through the receiver's articles for Sei's import, limit at a time. Return nextCursor
(any string) while there are more; Sei sends it back as cursor.
The article Sei sends
| Field | |
|---|---|
seiId |
Sei's id for the article. Stable. |
externalId |
Your id, once Sei has one (after a publish or an import). |
title, seoTitle, metaDescription, keyphrase |
Strings, possibly empty. |
slug |
Never empty from Sei: the article's slug, or one made from the title. A receiver that gets an empty one anyway (another sender, an older Sei) must make its own (keep the document's slug, or slugify the title), and never store an empty slug. With seoOnly, never replace a slug with an empty one. @getsei/webhook exports slugify(title). |
author |
The byline, when the article shows one. |
contentHtml |
The body as clean HTML (below). |
contentBlocks |
The same body as portable JSON (below). |
scores |
Sei's scores, 0–100: seo, readability, geo. |
updatedAt |
ISO 8601. |
categories? |
[{ "name", "slug" }] (1.1): the article's categories, the first one its main one. Sent when Sei knows the article's list on your site (it read it in an import or a pull, or sent it before), and with a new article that has some. Then it replaces yours: [] means the writer removed them all. Absent: leave the article's categories as they are (an older Sei, or a list Sei hasn't read from you yet). Never sent with seoOnly. |
tags? |
The same, for tags. |
contentHtml uses only h2–h4, p, ul/ol (with start)/li, blockquote, figure with one
img[src][alt] (and an optional title, and width/height in 1.8, below), table (1.7, below), a[href] (with
target/rel when the writer set them), strong, em and br. No classes, styles or scripts. Blocks are separated by a newline. Images keep their
absolute URLs: Sei doesn't upload files.
contentBlocks (blocksVersion: 1) is the shape Sei's analysis engine reads, with inline marks:
type SeiText = { text: string; links?: { href: string; start: number; end: number; rel?: string; target?: string }[]; marks?: { type: "bold" | "italic"; start: number; end: number }[] };
type SeiBlock =
| ({ type: "heading"; level: 2 | 3 | 4 } & SeiText)
| ({ type: "paragraph" } & SeiText)
| ({ type: "quote" } & SeiText) // a quote's paragraphs joined with "\n"
| { type: "list"; ordered: boolean; start?: number; items: (SeiText & { children?: SeiBlock[] })[] }
| { type: "image"; src: string; alt: string; title?: string; width?: number; height?: number } // width, height: 1.8
| { type: "table"; header: boolean; rows: SeiText[][] }; // 1.7Offsets count UTF-16 code units of text; a line break inside a block is \n. Newer versions may add block types:
skip a type you don't know (contentHtml always holds the whole body).
Image dimensions (1.8)
An image may carry its width and height in whole pixels (1 to 10000), each only when the article has one: as
attributes in contentHtml (<img src="…" alt="…" width="1400" height="933">) and as width/height numbers on
the image block in contentBlocks. They are the image's intrinsic display size: keep them on the <img> so the page doesn't shift while
it loads. Report them back in contentHtml the same way and an import keeps them. Any other size (width="100%",
width="auto", a style) makes the article read-only in Sei. A receiver built before 1.8 that ignores them loses
nothing but the attributes.
Tables (1.7)
A table is rows of cells, every row equally wide, no merged cells. Each cell is inline text (bold, italic, links,
line breaks). In contentHtml the first row is a header row in <thead> with <th> cells when the writer made it
one, and the other rows are in <tbody> with <td> cells:
<table><thead><tr><th>Kettle</th><th>Price</th></tr></thead><tbody><tr><td><strong>X1</strong></td><td>$40</td></tr></tbody></table>In contentBlocks it is { "type": "table", "header": true, "rows": [[{ "text": "Kettle" }, { "text": "Price" }], [{ "text": "X1", "marks": [{ "type": "bold", "start": 0, "end": 2 }] }, { "text": "$40" }]] }, the header row
included as rows[0]. A receiver built before 1.7 that renders contentHtml shows the table already; one that
builds its markup from contentBlocks skips it until it knows the type.
Report a table back in contentHtml the same way. Anything else in it (a colspan or rowspan, a <th> outside
the header row, a <caption>, a <tfoot>, a class or style, block markup such as <p> or a list in a cell) makes
the article read-only in Sei, like any other markup outside the elements above.
ExternalArticle (article.list items, and a conflict's current)
{
"externalId": "17",
"revision": "2026-10-19T09:30:02.114Z",
"title": "Pour-over coffee at home",
"slug": "pour-over-coffee",
"seoTitle": "Pour-over coffee at home | Harbor & Pine",
"metaDescription": "Brew a clean, bright cup in four minutes.",
"keyphrase": "pour-over coffee",
"status": "published",
"url": "https://blog.example/pour-over-coffee",
"updatedAt": "2026-10-19T09:30:02.114Z",
"contentHtml": "<h2>Gear</h2><p>A <strong>gooseneck</strong> kettle.</p>"
}revision must change whenever the article changes on your side, on every save: Sei never reads the article
before it publishes, so your ifRevision check is the only thing that stops Sei from overwriting an edit made on
your side. A timestamp only works when no two saves can share one: WordPress's modified_gmt has one-second
resolution, and an edit made within the same second as Sei's write would leave it unchanged (Sei's WordPress
adapter compares content for that reason). Use a version counter, a content hash, or a timestamp with millisecond
resolution or finer that your CMS sets on each save (Payload uses its updatedAt). status is
draft, published or scheduled. Sei imports contentHtml with the rules of its WordPress import: anything
outside the elements above (an <iframe>, a <div>, a class or style, an HTML comment) keeps its text but makes
the article read-only in Sei, and Sei then only ever sends seoOnly publishes for it. Mark what you can't
express that way on purpose, for example <div data-cms-node="gallery"></div>.
categories and tags (1.1, optional, the same { name, slug } lists): the article's terms, when you keep them.
Sei files the imported article under them.
Categories and tags (1.1)
Additive, inside sei-webhook/1 (the sei-protocol header stays 1):
- A term is
{ "name": "Brewing", "slug": "brewing" }. Terms are matched by slug; Sei makes slugs from names the wayslugifydoes. Store an unknown term as a new one. article.publishcarriesarticle.categoriesandarticle.tags(above), each list on its own and only when Sei knows yours: a list Sei never read from your site is left out, so it can't wipe terms Sei hasn't seen. A receiver without taxonomies ignores them, as a 1.0 receiver does.- Report each list you keep in
article.listand conflicts, even an empty one ([]): that is how Sei learns your list. A list you leave out is one Sei keeps as it is. ping'staxonomiescapability says the receiver stores them. Without it Sei still sends them (harmless).terms.list(no fields) answers the site's own terms for Sei's pickers, at most 1,000 of each kind:
{ "categories": [{ "name": "Brewing", "slug": "brewing" }, { "name": "Gear", "slug": "gear" }], "tags": [{ "name": "V60", "slug": "v60" }] } A receiver that can't list them answers 404 { "code": "unsupported" }; Sei then keeps each site's terms itself
(those on imported articles and those typed in Sei).
Delete and restore (1.2)
Sei's Delete moves an article to Sei's Trash for 30 days. With "Also delete it on article.delete to a receiver whose ping lists delete (a receiver without it is never asked, and the box isn't
shown). How to delete is the receiver's choice:
- delete for good, and answer
"recoverable": false; - or keep it out of sight (a
deletedAtcolumn, a status, your CMS's own trash) and answer"recoverable": true.
Restoring the article in Sei sends article.restore when the delete was recoverable and ping lists restore:
bring the article back as a draft (never live by itself) and answer like an unpublish. After a delete for good,
Sei's Restore brings the article back in Sei only, unlinked; publishing it creates a new article on the site.
With @getsei/webhook, onDelete and onRestore add the delete and restore capabilities.
Cover image (1.3)
article.featuredImage is the article's cover (featured) image, { "url", "alt" }, sent with every full publish of
an article that has one (never with seoOnly). The URL is public https: Sei's copy of the writer's upload, or an
image already on the site. Store it as the article's featured image (or copy the file into your own media). When
it is absent, keep the image the article has: removing the cover in Sei doesn't remove it on the site.
article.list items may carry featuredImage too: an import then sets the article's cover in Sei. Report only an
image that is the article's cover, not one taken from its body (the body's images are in contentHtml already).
Social title and description (1.6)
article.social is { "title", "description" }: the shared link's title and description, when the writer set them
apart from the SEO ones. It is sent with every full publish of an article that has them (never with seoOnly).
Print them as og:title, og:description, twitter:title and twitter:description; an empty one falls back to
seoTitle (else title) or metaDescription. When social is absent, keep what the article has.
Pages (1.6)
A receiver that keeps pages (About, Contact…) besides articles answers ping with the pages capability. Sei then
lets writers create pages there and imports them. A page carries "kind": "page": on article in article.publish
and article.preview, on article.unpublish, article.delete and article.restore, and on the article.list
items that are pages. An article never carries kind (or carries "article"). Pages get no categories, tags or
cover from Sei.
Publish dates (1.5)
publishedAt (ISO 8601) in the publish reply and in ExternalArticle: when the article first went live, null
while it never has. Keep it when the article is updated, so it stays the date the site lists it by. Sei orders its
Articles list's live articles by it; a receiver that leaves it out gets the first time Sei saw the article live.
Preview (1.4)
Sei's Preview button sends article.preview with the article as article.publish would send it (externalId
included when it is linked). Render it exactly as the site renders a published article, from the same page
component, so the boxes, categories, date and reading time the site builds itself all come from the draft. Never
save it as an article: keep it for a few minutes (10 is plenty) under a random token in a store every instance
shares, and answer with the URL that shows it:
{ "url": "https://blog.example/sei-preview/0b9f6c3e5a1d4c7e8f2a9b6d3c1e7f40" }The URL must be http(s) on the site's own host (Sei refuses another), work without cookies, and should send
noindex and no-cache headers. Sei's server loads it once and shows the page from Sei, with the site's styles and
images and without its scripts. A receiver that answers 404 unsupported (or a 1.3 one) gets Sei's fallback: the
draft placed into the page of one of its published articles, which can't know the boxes the site builds itself.
With @getsei/webhook, onPreview adds the preview capability.
Drafts over published articles (hasPendingDraft)
status says what readers see. Some CMSs keep a published article live while a newer draft of it is edited
(Payload with drafts, Sanity, Contentful); others take the article offline when it is saved as a draft (WordPress).
- A receiver of the first kind answers a
draftorschedulepublish over a published article withstatus: "published"andhasPendingDraft: true, and lists such an article the same way (thetitle,contentHtmland the rest are then the draft's). Sei shows it as Published · draft pending. - A receiver of the second kind answers with
status: "draft"(or"scheduled") and leaveshasPendingDraftout: the article is offline until it is published again. hasPendingDraftis optional and only means something withstatus: "published"; Sei ignores it otherwise.article.unpublishdrops any pending draft's flag: the article is a draft.
| Target | Save as draft on a published article | Sei shows |
|---|---|---|
| WordPress | The post goes back to a draft (offline) | Draft |
@getsei/payload (drafts on) |
A draft version; the published one stays live | Published · draft pending |
@getsei/payload (no drafts) |
Refused: 422 unsupported-mode (see capabilities drafts) |
Errors
| Answer | Sei shows |
|---|---|
401 / 403 |
"The site refused Sei's signature": the secrets differ. Settings asks for a new secret. |
404 { "code": "unsupported" } |
The receiver doesn't do this (unpublish, list, terms.list). |
409 { "code": "conflict", "current": ExternalArticle } |
The conflict banner (below). |
422 { "code": "unsupported-mode", "message" } |
The message: no drafts or scheduling. |
any other 4xx/5xx { "code", "message" } |
The message, on one line, cut to 300 characters. |
Conflicts
When ifRevision doesn't match, answer 409 with the article as it is now. Sei refuses to publish and offers:
- Overwrite: the same publish without
ifRevision. - Pull into editor: Sei replaces its version with
current(its HTML, title, slug and SEO fields). - Save as new draft: a publish with no
externalId,mode: "draft"andasNew: true.
If current already holds exactly what Sei sends (Sei's own write whose answer was lost), Sei sends it once more
with ifRevision set to current.revision instead of showing the banner.
A receiver in 15 lines (Next.js)
// app/api/sei/webhook/route.ts — npm i @getsei/webhook (see packages/webhook/README.md)
import { createSeiHandler, SeiConflict } from "@getsei/webhook/next";
import { posts } from "@/lib/posts"; // your storage
export const POST = createSeiHandler({
secret: process.env.SEI_WEBHOOK_SECRET!,
onPing: () => ({ name: "My blog" }),
async onPublish({ article, mode, ifRevision, asNew }) {
const found = article.externalId ? await posts.get(article.externalId) : asNew ? null : await posts.findBySeiId(article.seiId);
if (found && ifRevision && found.revision !== ifRevision) throw new SeiConflict(posts.toExternal(found));
const saved = await posts.save({ id: found?.id, seiId: article.seiId, title: article.title, slug: article.slug, html: article.contentHtml, draft: mode !== "publish", ...(article.categories ? { categories: article.categories, tags: article.tags ?? [] } : {}) });
return { externalId: saved.id, revision: saved.revision, status: mode === "publish" ? "published" : "draft", url: `https://blog.example/${saved.slug}` };
},
});createSeiHandler verifies the signature and timestamp, routes by type, answers 404 unsupported for handlers
you leave out (onUnpublish, onList), turns throw new SeiConflict(current) into the 409, and throw new SeiError(status, code, message) into that status. Express: app.post("/api/sei/webhook", seiExpress(handler))
from @getsei/webhook/express, mounted before any JSON body parser.