Receive Sei's signed webhooks in any JavaScript server: verify them (Standard Webhooks
signatures, Web Crypto only), route them, and answer in Sei's protocol. MIT, no runtime dependencies. Runs on Node 20+
(tested on 24), Edge runtimes and Bun. It implements Sei's webhook protocol, sei-webhook/1: the events and the
replies are the types and helpers below.
Sei is an SEO and GEO (AI-answer) writing tool: it scores articles as you write and publishes them to your site. A
"custom site" in Sei is any stack with one HTTPS endpoint that receives Sei's signed webhooks; this package is that
endpoint for JavaScript servers. For Payload CMS, use @getsei/payload.
Install
npm install @getsei/webhookES modules with TypeScript types (TypeScript 5.7 or newer reads them). Entry points: @getsei/webhook (everything),
@getsei/webhook/next (Next.js App Router), @getsei/webhook/express (Express or plain node:http),
@getsei/webhook/url and @getsei/webhook/slug (helpers).
Quick start
- In Sei: Settings → your site → Custom site. Enter your endpoint's URL and generate the signing secret.
- Put the secret in your server's environment as
SEI_WEBHOOK_SECRET. - Add the handler (Next.js or Express below), deploy, then click Test connection in Sei.
Next.js
// app/api/sei/webhook/route.ts
import { createSeiHandler, SeiConflict, SeiError } from "@getsei/webhook/next";
export const POST = createSeiHandler({
secret: process.env.SEI_WEBHOOK_SECRET!, // or () => readSecret(), read per request
onPing: () => ({ name: "My blog", timezone: "Europe/Berlin", capabilities: ["drafts"] }), // drafts, schedule: what you support
async onPublish({ article, mode, scheduledAt, ifRevision, seoOnly, asNew }) {
// … create or update; throw new SeiConflict(current) when ifRevision is stale,
// throw new SeiError(422, "unsupported-mode", "No drafts here.") for what you can't do.
return { externalId: "17", revision: "2026-10-19T09:30:02.114Z", status: "published", url: "https://blog.example/x" };
},
onUnpublish: async ({ externalId, ifRevision }) => ({ externalId, revision: "…", status: "draft" }), // optional
onList: async ({ cursor, limit }) => ({ items: [], nextCursor: undefined }), // optional
onTerms: async () => ({ categories: [{ name: "Brewing", slug: "brewing" }], tags: [] }), // optional (1.1)
onDelete: async ({ externalId }) => ({ externalId, recoverable: true }), // optional (1.2): your way, see below
onRestore: async ({ externalId }) => ({ externalId, revision: "…", status: "draft" }), // optional (1.2)
onPreview: async ({ article }) => ({ url: await keepPreview(article) }), // optional (1.4): see below
seen: (webhookId) => alreadySeen(webhookId), // optional dedupe store: true for a repeat (shared by all instances)
});revision must change on every save of the article on your side (a version counter, a content hash, or a
millisecond timestamp your CMS sets on each save): Sei relies on your ifRevision check alone to avoid overwriting
an edit made there. A one-second timestamp misses an edit made within the same second as Sei's write.
Categories and tags (1.1)
Sei 1.1 sends article.categories and article.tags ({ name, slug }[], the first category the main one) when it
knows the article's list on your site, and with a new article that has some; a list it sends replaces yours. Absent
means keep what the article has (an older Sei, or a list Sei hasn't read from you yet). normalizeTerms(list) cleans them
(names trimmed, slugs made where empty, each slug once). Give onTerms to list your site's terms in Sei's pickers
(terms.list, and the taxonomies capability in ping); a receiver that stores terms but can't list them says
capabilities: ["taxonomies"] in onPing. Receivers built on 1.0 keep working: they ignore the new fields.
Delete and restore (1.2)
When a writer deletes an article in Sei and ticks "Also delete it on article.delete to a
receiver with onDelete. You decide how: delete the row for good and answer recoverable: false, or hide it (a
deletedAt column, a status) and answer recoverable: true, so restoring it in Sei sends article.restore to
onRestore, which brings it back as a draft. Without onDelete, Sei never asks your site to delete.
Cover image (1.3)
An article with a cover (featured) image comes with article.featuredImage: { url, alt }: a public https URL (Sei's
copy of the upload, or an image already on your site). Store the URL, or copy the file into your own media, and use
it for your hero image, og:image and JSON-LD. Without featuredImage, keep the image the article has. List it back
in article.list items as featuredImage and an import brings it into Sei as the article's cover.
Publish dates (1.5)
Answer publishedAt (ISO 8601, when the article first went live; null while it never has) in the publish reply and
in article.list items. Sei's Articles list then orders live articles the way your site lists them. Without it, Sei
uses the first time it saw the article live, which for an imported article is the import.
Image dimensions (1.8)
An image in the body may carry its size in whole pixels: <img src alt width="1400" height="933"> in contentHtml
and width/height on the image block in contentBlocks (the SeiImageBlock type), each only when the article
has one. Keep them on the <img> (they reserve the image's space while it loads) and report them back the same way:
an import keeps them. A size Sei can't write back (a percentage, a style) makes the article read-only in Sei.
Preview (1.4)
Sei's Preview button sends article.preview with the same article article.publish would send. Keep it for a few
minutes (a table, Redis: something every instance shares) under a random token, and answer with a URL on your site
that renders it exactly like a published article, from the same page component, without saving it as an article:
onPreview: async ({ article }) => {
const token = crypto.randomUUID();
await db.previews.insert({ token, article, expiresAt: new Date(Date.now() + 10 * 60_000) });
return { url: `https://blog.example/sei-preview/${token}` };
},The URL must be on your site's host, work without cookies (Sei's server loads it once, then shows the page in Sei
with your styles and without scripts), and should send noindex. Without onPreview, Sei shows the draft in a
published article's page instead, which can't know the boxes your site builds itself.
Express (or plain node:http)
The signature covers the raw body, so mount the handler before express.json(), or give it
express.raw({ type: "application/json" }):
import { createSeiHandler } from "@getsei/webhook";
import { seiExpress } from "@getsei/webhook/express";
app.post("/api/sei/webhook", seiExpress(createSeiHandler({ secret: process.env.SEI_WEBHOOK_SECRET!, onPublish })));API
createSeiHandler(options)→(req: Request) => Promise<Response>. Verifies, refuses repeats (seen), routes bytype, and answers: the handler's result as200;SeiConflictas409 { code: "conflict", current };SeiError(status, code, message)as that status; a missing handler as404 { code: "unsupported" }; a body overmaxBodyBytes(default 5 MB) as413, before it is read in full; a bad signature or timestamp as401; a malformed event as400; any other error as500(its message is never sent;onErrorgets it,console.errorby default). Ping'scapabilitiescome from the handlers you pass.verifySeiWebhook(request | { headers, body }, secret, { toleranceSec = 300, maxBodyBytes = 5 MB })→ the typedSeiEvent, or throwsSeiWebhookError(code:missing-headers,invalid-timestamp,timestamp-too-old,timestamp-too-new,invalid-signature,unsupported-protocol,invalid-body,invalid-secret,body-too-large).bodymust be the raw bytes. A Request's body is read with the limit: refused on itscontent-length, else as soon as it streams past it.readBody(request, max)is that read on its own.seiExpress(handler, { maxBodyBytes }): the same limit on the request stream, answered with413.verifySignature(...): the Standard Webhooks check alone, for any payload.signSeiWebhook({ id, timestamp, body, secret })andseiWebhookHeaders(...): what a sender (Sei, a test) needs.generateSecret(): a newwhsec_secret (32 random bytes).decodeSecret(secret): its key bytes.normalizeTerms(terms): categories or tags as a receiver should store them (1.1).- Types:
SeiArticle,ExternalArticle,SeiEventand each event,SeiPingReply,SeiPublishReply,SeiUnpublishReply,SeiListReply,SeiTermsReply,SeiPreviewReply,SeiTerm,SeiContentBlocks,SeiBlock,SeiTableBlock(1.7),SeiImageBlock(1.8).
Develop
The package is developed in Sei's monorepo, which is private; npm gets the compiled dist/ (ES modules with .d.ts
types, not minified). In the monorepo the package is used from its TypeScript source ("@getsei/webhook": "workspace:*", with Next.js
transpilePackages); pnpm --filter @getsei/webhook build compiles dist/, which is what npm gets.
pnpm --filter @getsei/webhook test # Standard Webhooks vectors, tolerance, tampering, dedupe, the handler, Express
pnpm --filter @getsei/webhook typecheck
pnpm --filter @getsei/webhook build # dist/ (ES modules and .d.ts)License
MIT