Retries and duplicates

What your answer means

Your endpoint	What happens
Answers 2xx	Delivered. Nothing more is sent for this delivery.
Doesn’t answer within 15 seconds, or the connection fails	Tried again.
Answers 408, 429 or any 5xx	Tried again.
Answers any other 4xx	Not tried again. Your endpoint said no.
Answers with a redirect (3xx)	Not followed, and not tried again. A post goes only to the address you gave.

A post is tried again a few times, with a wait between tries. If your endpoint never takes it, we let it go: the article is live either way, and the feed still has it.

A webhook is a nudge, not the record

Don’t rely on webhooks alone to know what is live. The feed is the record. If your endpoint was down for a while, fetch the feed to catch up.

The same delivery twice

Because a post can be tried again, your endpoint can get the same delivery more than once, for example when it did the work but answered too slowly.

Every try of the same post has the same delivery ID, in the body and in the citedseo-delivery header. To do the work once, remember the IDs you have handled:

export async function POST(request: Request) {
  const body = await request.text();
  // …verify the signature first…
  const post = JSON.parse(body);

  if (await seen(post.delivery)) return new Response(null, { status: 204 });

  await handle(post);
  // Only once the work is done, so a try that failed is done again on the next.
  await remember(post.delivery);
  return new Response(null, { status: 204 });
}

A try is sent again after 15 seconds with no answer, so two tries of one delivery can overlap when the work is slow, and both get past seen. Make handle safe to run twice, for example by keeping whichever version of an article has the later modifiedAt, or claim the ID in one atomic step in your store and release it if the work fails.

Often you don’t need even that. If all you do is rebuild or clear a cache, doing it twice is harmless.

Answer first, work after

You have 15 seconds to answer. A rebuild or a slow call to another service can take longer, and a slow answer is tried again. Verify, queue the work, answer 2xx, then do the work.

Order

Each article’s events are sent as it publishes, and each post carries the article as it is live at that moment. If two posts for the same article arrive close together, keep the one with the later modifiedAt.