Sei
FeaturesIntegrationsFAQ
Start
  • Overview
  • WordPress
  • Custom site quick start
Reference
  • Operations
  • Webhook protocol
  • @getsei/webhook
  • @getsei/payload
Help
  • Troubleshooting
  • Changelog

Docs

Sei webhook protocol (sei-webhook/1)

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> with Content-Type: application/json and 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 or localhost endpoint only works with a local Sei in development).
  • Sei waits 20 seconds for ping and article.list, 40 seconds for article.publish and article.unpublish.
  • Sei reads at most 2 MB of the answer, and never follows a redirect: a 3xx is 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

  1. Read the raw body exactly as it arrived, before any JSON parsing.
  2. Refuse the request if webhook-id, webhook-timestamp or webhook-signature is missing.
  3. Refuse it if the timestamp is more than 5 minutes from your clock, either way (a replayed request is old).
  4. Take the key: the secret without whsec_, base64-decoded. Compute HMAC-SHA256 over the UTF-8 bytes of webhook-id + "." + webhook-timestamp + "." + body, and base64 it.
  5. Accept the request if any v1,<signature> in the header equals it. Compare in constant time (crypto.timingSafeEqual, hmac.compare_digest, hash_equals).
  6. Treat a webhook-id you have already seen as a duplicate (keep ids at least 10 minutes). @getsei/webhook takes a seen hook 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), or schedule (live at scheduledAt, ISO 8601). A receiver without drafts or scheduling answers 422 { "code": "unsupported-mode" }.
  • article.externalId absent: a create. Sei may retry a create whose answer it never got (a timeout): find the article you created for the same article.seiId and update it instead of creating a second one.
  • ifRevision: update only if the article is still at this revision (what your last answer called revision); otherwise answer 409 (below). Sei leaves it out when the person chose "Overwrite".
  • seoOnly: true: the article has content Sei can't represent. Update only slug, seoTitle, metaDescription and keyphrase: 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 this seiId; 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.7

Offsets 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 way slugify does. Store an unknown term as a new one.
  • article.publish carries article.categories and article.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.list and 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's taxonomies capability 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 " ticked, it also sends 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 deletedAt column, 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 draft or schedule publish over a published article with status: "published" and hasPendingDraft: true, and lists such an article the same way (the title, contentHtml and 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 leaves hasPendingDraft out: the article is offline until it is published again.
  • hasPendingDraft is optional and only means something with status: "published"; Sei ignores it otherwise. article.unpublish drops 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" and asNew: 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.

On this page
  • Transport
  • Signing (Standard Webhooks)
  • Requests
  • Errors
  • A receiver in 15 lines (Next.js)
PrivacyTermsDocsSeiBot