A Payload CMS 3 plugin that lets Sei publish to one collection,
and import from it, through Sei's signed webhook
(protocol sei-webhook/1). MIT. Tested with Payload 3.90.2.
Built on @getsei/webhook.
Install
npm install @getsei/payloadES modules with TypeScript types. In the Next.js app that runs Payload, keep jsdom (which the plugin uses to turn
Sei's HTML into Lexical) out of the bundle: serverExternalPackages: ["jsdom"] in next.config.
Quick start
- Add
seiPlugintopayload.config.ts(below) and, for images,seiImageBlockto the content field's editor (for tables,EXPERIMENTAL_TableFeaturetoo). - Create a migration if your database adapter runs without
push(see Migrations). - In Sei: Settings → your site → Custom site. Enter
https://<your site>/api/sei/webhook, generate the secret, set it asSEI_WEBHOOK_SECRETon the site, deploy, then click Test connection.
Compatibility. Peer dependencies: payload and @payloadcms/richtext-lexical >=3.90.2 <3.91.0, the release line
the integration tests run against. The range is narrow on purpose: the plugin relies on parts of Payload that change
between minor releases without notice: convertHTMLToLexical and editorConfigFactory.fromField, the blocks
feature's resolved server props (to find seiImage), the schedulePublish job's input and the payload-jobs fields
(to find and cancel a scheduled publish), and how a draft save leaves the published version in the document. A new
Payload minor gets the range widened once pnpm --filter @getsei/payload test passes on it.
Use
// payload.config.ts
import { seoPlugin } from "@payloadcms/plugin-seo";
import { BlocksFeature, EXPERIMENTAL_TableFeature, lexicalEditor } from "@payloadcms/richtext-lexical";
import { seiImageBlock, seiPlugin } from "@getsei/payload";
export default buildConfig({
collections: [
{
slug: "posts",
versions: { drafts: { schedulePublish: true } }, // drafts and scheduling in Sei; optional
fields: [
{ name: "title", type: "text", required: true },
{ name: "slug", type: "text" },
// seiImageBlock keeps Sei's images (absolute URLs) in Lexical; without it, an article with images is refused.
// EXPERIMENTAL_TableFeature keeps Sei's tables (1.5); without it, a table becomes one paragraph per row.
{ name: "content", type: "richText", editor: lexicalEditor({ features: ({ defaultFeatures }) => [...defaultFeatures, BlocksFeature({ blocks: [seiImageBlock] }), EXPERIMENTAL_TableFeature()] }) },
{ name: "publishedAt", type: "date" },
],
},
],
plugins: [
seoPlugin({ collections: ["posts"] }), // optional; list it before seiPlugin
seiPlugin({
secret: () => process.env.SEI_WEBHOOK_SECRET, // from Sei: Settings → the site → Custom site → Generate secret
collection: "posts",
fields: { title: "title", slug: "slug", content: "content", publishedAt: "publishedAt" },
seo: "auto",
url: (doc) => `https://blog.example/posts/${doc.slug}`,
name: "My blog",
taxonomies: true, // optional (1.1): categories and tags from Sei
}),
],
// …
});Then in Sei, enter https://<your site>/api/sei/webhook as the custom site's endpoint, generate the secret, set
SEI_WEBHOOK_SECRET and Test connection.
Migrations (Postgres, SQLite). The plugin changes the schema: it adds the seiArticleId field and the sei group
to the collection and, with dedupe: "collection" (the default), the hidden sei-webhook-deliveries collection.
In development the adapter's push creates them. A site that runs without push, as production does, needs a
migration after adding the plugin (and after a plugin update that changes its fields), before the new build serves
requests: the endpoint fails on the missing table until then.
pnpm payload migrate:create add-sei-plugin # commit the generated migration
pnpm payload migrate # on each environment, before the new build goes liveMongoDB needs no migration.
What it does
Endpoint
POST /api/sei/webhook(a Payload custom endpoint), throughcreateSeiHandlerfrom@getsei/webhook: signature, 5-minute timestamp tolerance, and a dedupe of delivery ids (kept 10 minutes) in a hiddensei-webhook-deliveriescollection, so a replay is refused on every instance that shares the database (rows older than 10 minutes are purged on each write).dedupe: "memory"keeps them in memory instead (memoryDedupe): per server instance only, so a replay that reaches another instance (serverless, several containers) gets through. Use it only for a single long-running process.Fields on the collection:
seiArticleId(hidden, indexed: a retried create finds the document it made), and aseigroup:keyphrase, plusseoTitleandmetaDescriptionunless@payloadcms/plugin-seois there (seo: "auto"), in which case Sei writesmeta.titleandmeta.description.seo: "sei"always uses the group.Content:
contentHtml→ Lexical through Payload'sconvertHTMLToLexicalon a jsdom document; images becomeseiImageblocks. Back to Sei (article.list, conflicts) throughconvertLexicalToHTMLwith clean converters (seiHtmlConverters): what Sei can't represent (uploads, relationships, other blocks, underline, alignment) leaves a trace, and Sei imports that article read-only.Image dimensions (1.6): an image's
widthandheight(whole pixels, from@getsei/webhook1.8) are kept as theseiImageblock'swidthandheightnumber fields and read back on its<img>. The block's fields live in the rich text JSON, so adding them needs no migration.Tables (1.5): with
EXPERIMENTAL_TableFeatureon the content field, Sei's tables become Lexical tables (a header row as row-header cells) and read back as the same HTML. Without it, each row becomes a paragraph of its cells ("Kettle · $40"), so no text is lost, and the table is gone from that article. Sei's tables are simple: what it can't hold (merged cells, a header column, cell colors, column widths, several paragraphs in a cell) leaves a trace like the rest, and Sei imports that article read-only.Drafts (
_status) when the collection hasversions.drafts; scheduling through Payload's scheduled publish (versions.drafts.schedulePublish, aschedulePublishjob at the time). Without them,draftandscheduleanswer422 unsupported-mode. A draft or schedule over a published document keeps the published version live: Sei getsstatus: "published"withhasPendingDraft: true(in the reply,article.listand conflicts) and shows "Published · draft pending". A newer publish, draft or schedule cancels any scheduled publish that hasn't run, overdue ones included. Scheduled jobs need Payload's job runner (jobs.autoRun, orpayload jobs:run).Conflicts: the revision is the document's
updatedAt(ISO 8601 with milliseconds, set on every save); a staleifRevisionanswers409with the document.Slugs: never written empty: Sei's slug, else the document's own, else
slugify(title). AseoOnlyupdate never replaces a slug with an empty one.Categories and tags (1.1, opt-in with
taxonomies: true): acategoriesand atagscollection (name, uniqueslug, readable by anyone) andhasManyrelationship fieldscategoriesandtagson the collection. A collection the config already has is used instead when it has a textslugfield and a texttitleornamefield (taxonomies: { categories: "topics" }names another one). Sei's terms are matched by slug and created when missing; a publish without them (an older Sei) leaves the document's as they are, andseoOnlynever touches them.article.listand conflicts report them,terms.listlists both collections (ping saystaxonomies). Off by default: turning it on adds tables and fields, so it needs a migration like the plugin itself. Access of the collections the plugin adds: create, update and delete follow the collection Sei publishes to (its own rules, or logged-in users when it sets none); reading is for logged-in users only, unlesstaxonomies: { publicRead: true }. That is off by default because a term can exist for drafts alone, and a public API would show its name before the article is out. A collection the site already has keeps its own rules. A reused collection with required fields Sei doesn't fill answers422 terms-not-savednaming it.Delete and restore (1.2): Sei's Delete with "Also delete it on
" deletes the document for good by default ( delete: true).delete: { field: "deletedAt" }keeps it instead, with that date field set: it leavesarticle.list, and Sei's Restore clears the field and makes it a draft again (ping then saysrestoretoo). With Payload's own trash (trash: trueon the collection), name itsdeletedAtfield.delete: false: Sei never deletes here (ping leaves outdelete).Cover image (1.3): name a field in
fields.featuredImageto store Sei's cover. A text field gets the image's URL (fields.featuredImageAlt, another text field, its alt text). An upload field gets a document of its upload collection: the plugin downloads Sei's image once (again only when Sei sends another one) and sets the collection'saltto the cover's alt text (or the article's title). A publish without a cover keeps the field, and an import reads it back (an upload's URL needsserverURLin the config when Payload serves it relatively).Preview (1.4): with
preview: { url: (doc, token) => … }, Sei's Preview button shows a draft on your own article page, your theme and scripts included. The plugin converts the draft as a publish would and keeps it for ten minutes under a random token, in a hiddensei-previewscollection; nothing is written to your collection. Your page reads it back by the token and renders it like a published article:// payload.config.ts seiPlugin({ secret, preview: { url: (doc, token) => `https://example.com/blog/${doc.slug}?sei_preview=${token}` } }) // app/blog/[slug]/page.tsx const draft = await getSeiPreview(payload, (await searchParams).sei_preview); const post = draft ?? (await findPublishedPost(slug));The draft has the collection's fields (and
seiPreviewCover: { url, alt }when Sei sent a cover). Mark the pagenoindexand don't cache it whilesei_previewis set.Pages (1.4):
pages: { collection: "pages" }lets Sei import, write and publish the site's pages too, in that collection (itstitle,slugandcontentfields, or the names inpages.fields;pages.urlnames a page's public URL). Pages get Sei's SEO fields, and no categories, tags or cover.Old URLs (1.5): when Sei publishes a new slug for a live document, the plugin keeps the old one in
sei.previousSlugs(read-only in the admin). A draft or a scheduled publish with a new slug changes no URL yet, and a slug the document takes back leaves the list. Your route asksfindSeiRedirectabout a slug it found nothing for and redirects with a 301:// app/blog/[slug]/page.tsx const post = await findPublishedPost(slug); if (!post) { const moved = await findSeiRedirect(payload, { collection: "posts", slug }); if (moved) permanentRedirect(`/blog/${moved.slug}`); notFound(); }A slug another published document now has is never redirected. Adding the field needs a migration, like any plugin update that changes its fields (see Migrations).
Access: every write is a Local API call with
overrideAccess: true, on the configured collection only: the signature is the authorization. Keep the secret secret.
Options: secret (string or function), collection (default "posts"), fields (title, slug, content,
optional publishedAt, author, featuredImage, featuredImageAlt), seo ("auto" or "sei"), url(doc), name, timezone, enabled,
maxBodyBytes (default 5 MB: a larger request gets 413 before it is read), taxonomies (1.1, default off),
delete (1.2: true by default, { field }, or false), preview (1.4: { url(doc, token) }, off by default), pages (1.4: { collection, fields?, url? }, off by default).
API
seiPlugin(options): the Payload plugin (options above).seiImageBlock: the Lexical block that holds Sei's images (add it withBlocksFeature).seiHtmlConverters: the Lexical → HTML converters the plugin uses, for rendering Sei's content safely.getSeiPreview(payload, token): the draft Sei asked to preview, or null (unknown or older than ten minutes).findSeiRedirect(payload, { collection, slug, slugField? }): the published document that used to haveslug, as{ id, slug }with its current slug, or null (1.5).collectionDedupe,memoryDedupe,DELIVERIES_SLUG,PREVIEWS_SLUG: the replay stores (dedupeoption) and the previews' collection.SEI_GROUP,SEI_ID_FIELD,ENDPOINT_PATH: the field and endpoint names.- Types:
SeiPluginOptions,SeiFieldNames,SeiRedirectQuery.
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:
pnpm --filter @getsei/payload test # a real Payload on SQLite (temp files) in vitest
pnpm --filter @getsei/payload typecheck
pnpm --filter @getsei/payload build # dist/ (ES modules and .d.ts)examples/payload-sandbox runs it in a full Payload + Next app on :3400.
License
MIT