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

Docs

@getsei/payload

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

ES 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

  1. Add seiPlugin to payload.config.ts (below) and, for images, seiImageBlock to the content field's editor (for tables, EXPERIMENTAL_TableFeature too).
  2. Create a migration if your database adapter runs without push (see Migrations).
  3. In Sei: Settings → your site → Custom site. Enter https://<your site>/api/sei/webhook, generate the secret, set it as SEI_WEBHOOK_SECRET on 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 live

MongoDB needs no migration.

What it does

  • Endpoint POST /api/sei/webhook (a Payload custom endpoint), through createSeiHandler from @getsei/webhook: signature, 5-minute timestamp tolerance, and a dedupe of delivery ids (kept 10 minutes) in a hidden sei-webhook-deliveries collection, 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 a sei group: keyphrase, plus seoTitle and metaDescription unless @payloadcms/plugin-seo is there (seo: "auto"), in which case Sei writes meta.title and meta.description. seo: "sei" always uses the group.

  • Content: contentHtml → Lexical through Payload's convertHTMLToLexical on a jsdom document; images become seiImage blocks. Back to Sei (article.list, conflicts) through convertLexicalToHTML with 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 width and height (whole pixels, from @getsei/webhook 1.8) are kept as the seiImage block's width and height number 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_TableFeature on 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 has versions.drafts; scheduling through Payload's scheduled publish (versions.drafts.schedulePublish, a schedulePublish job at the time). Without them, draft and schedule answer 422 unsupported-mode. A draft or schedule over a published document keeps the published version live: Sei gets status: "published" with hasPendingDraft: true (in the reply, article.list and 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, or payload jobs:run).

  • Conflicts: the revision is the document's updatedAt (ISO 8601 with milliseconds, set on every save); a stale ifRevision answers 409 with the document.

  • Slugs: never written empty: Sei's slug, else the document's own, else slugify(title). A seoOnly update never replaces a slug with an empty one.

  • Categories and tags (1.1, opt-in with taxonomies: true): a categories and a tags collection (name, unique slug, readable by anyone) and hasMany relationship fields categories and tags on the collection. A collection the config already has is used instead when it has a text slug field and a text title or name field (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, and seoOnly never touches them. article.list and conflicts report them, terms.list lists both collections (ping says taxonomies). 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, unless taxonomies: { 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 answers 422 terms-not-saved naming 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 leaves article.list, and Sei's Restore clears the field and makes it a draft again (ping then says restore too). With Payload's own trash (trash: true on the collection), name its deletedAt field. delete: false: Sei never deletes here (ping leaves out delete).

  • Cover image (1.3): name a field in fields.featuredImage to 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's alt to 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 needs serverURL in 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 hidden sei-previews collection; 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 page noindex and don't cache it while sei_preview is set.

  • Pages (1.4): pages: { collection: "pages" } lets Sei import, write and publish the site's pages too, in that collection (its title, slug and content fields, or the names in pages.fields; pages.url names 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 asks findSeiRedirect about 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 with BlocksFeature).
  • 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 have slug, as { id, slug } with its current slug, or null (1.5).
  • collectionDedupe, memoryDedupe, DELIVERIES_SLUG, PREVIEWS_SLUG: the replay stores (dedupe option) 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

On this page
  • Install
  • Quick start
  • Use
  • What it does
  • API
  • Develop
  • License
PrivacyTermsDocsSeiBot