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

Docs

@getsei/webhook

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/webhook

ES 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

  1. In Sei: Settings → your site → Custom site. Enter your endpoint's URL and generate the signing secret.
  2. Put the secret in your server's environment as SEI_WEBHOOK_SECRET.
  3. 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 ", Sei sends 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 by type, and answers: the handler's result as 200; SeiConflict as 409 { code: "conflict", current }; SeiError(status, code, message) as that status; a missing handler as 404 { code: "unsupported" }; a body over maxBodyBytes (default 5 MB) as 413, before it is read in full; a bad signature or timestamp as 401; a malformed event as 400; any other error as 500 (its message is never sent; onError gets it, console.error by default). Ping's capabilities come from the handlers you pass.
  • verifySeiWebhook(request | { headers, body }, secret, { toleranceSec = 300, maxBodyBytes = 5 MB }) → the typed SeiEvent, or throws SeiWebhookError (code: missing-headers, invalid-timestamp, timestamp-too-old, timestamp-too-new, invalid-signature, unsupported-protocol, invalid-body, invalid-secret, body-too-large). body must be the raw bytes. A Request's body is read with the limit: refused on its content-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 with 413.
  • verifySignature(...): the Standard Webhooks check alone, for any payload.
  • signSeiWebhook({ id, timestamp, body, secret }) and seiWebhookHeaders(...): what a sender (Sei, a test) needs.
  • generateSecret(): a new whsec_ 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, SeiEvent and 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

On this page
  • Install
  • Quick start
  • Next.js
  • Categories and tags (1.1)
  • Delete and restore (1.2)
  • Cover image (1.3)
  • Publish dates (1.5)
  • Image dimensions (1.8)
  • Preview (1.4)
  • Express (or plain node:http)
  • API
  • Develop
  • License
PrivacyTermsDocsSeiBot