Events and payload

Events

There are two.

Event	Sent when
`article.published`	An article goes live: the first time, or again after it was taken down.
`article.updated`	An article that is already live changes: an update, new links, a new title, or an undo that ships.

The request

Each event is one POST to your endpoint with a JSON body.

Headers

content-typeapplication/json
citedseo-eventstring: The event’s name, the same as event in the body.
citedseo-deliverystring: This delivery’s ID, the same as delivery in the body. It is the same on every try of the same post. See Retries and duplicates.
citedseo-signaturestring: t=<unix seconds>,v1=<signature>. See Verify the signature.

Body

eventstring: article.published or article.updated.
deliverystring: This delivery’s ID. Treat it as an opaque string.
dataArticle: The article as it is live now, in the same shape the feed serves.

{
  "event": "article.published",
  "delivery": "5d1c3b0a-8e42-4f6b-9a57-0c2f1e9b7d44:b7a1f3c2-6d58-4e0a-8c39-41f2a9d05e16",
  "data": {
    "id": "0b6f6c1e-3f0a-4a59-9d0e-2f8f4c1f7a31",
    "slug": "how-to-brew-green-tea",
    "url": "https://example.com/blog/how-to-brew-green-tea",
    "title": "How to brew green tea",
    "description": "Brew green tea at 80°C for two minutes. Here is why the temp…",
    "cover": {
      "src": "https://example.com/images/green-tea.webp",
      "alt": "A glass teapot of green tea"
    },
    "author": {
      "name": "Sam Lee",
      "url": "https://example.com/authors/sam-lee"
    },
    "publishedAt": "2026-10-09T02:05:00.000Z",
    "modifiedAt": "2026-10-11T02:05:00.000Z",
    "html": "<p class=\"citedseo-answer\"><strong>Brew green tea at 80°C for two minutes. Hot…",
    "markdown": "**Brew green tea at 80°C for two minutes. Hotter water makes…",
    "structuredData": {
      "@context": "https://schema.org",
      "@graph": [
        "…"
      ]
    }
  }
}

The long fields are cut short above. A real post carries the whole article.

TypeScript

The types come with the packages:

import type { WebhookEvent, WebhookPost } from '@citedseo/feed';

/** What every read takes. */
export type FeedOptions = {
  /** Your site ID. It is the only thing the feed needs. */
  siteId: string
  /** Another origin to read from, for tests. Defaults to https://feeds.citedseo.ai. */
  origin?: string
  /** Your own fetch: a framework's caching one, or a test's. Defaults to the global fetch. */
  fetch?: typeof fetch
}

/** What every read takes. */
export type FeedOptions = {
  /** Your site ID. It is the only thing the feed needs. */
  siteId: string
  /** Another origin to read from, for tests. Defaults to https://feeds.citedseo.ai. */
  origin?: string
  /** Your own fetch: a framework's caching one, or a test's. Defaults to the global fetch. */
  fetch?: typeof fetch
}