Skip to main content
An idempotent webhook receiver applies a repeated delivery without creating another article. It must also allow legitimate later edits to that article. Store blog_id as the article identity, and treat scheduled retry metadata as delivery information rather than a unique content revision. Manual and scheduled publishing handle failures differently.

Manual publish (you click Publish)

A manual webhook publish sends one request rather than entering the scheduled worker’s automatic retry sequence. Its client has a configured 30-second timeout. A timeout leaves the receiver’s outcome uncertain: the article may have been saved before its response was lost. Inspect your stored article and delivery logs before trying again. Manual webhook publishing accepts 200, 201, 202 and 204, then checks the response for an explicit rejection. For example, {"ignored":true,"reason":"Unsupported event"} is a failure even with HTTP 200. Return a supported acknowledgement using the response contract; do not report success for an event your receiver did not apply.

Autopilot publish (theStacc publishes on a schedule)

Scheduled publishing uses a fast retry tier followed by a slower tier for classified transient failures. The fast tier includes the first five attempts. If a transient failure continues, the configured slow delays are 1 hour, 3 hours and 12 hours. Once those delays are exhausted, another transient failure is marked failed. A permanent error stops without entering that retry sequence. For scheduled webhooks, timeouts and network errors are transient. The initial HTTP classification treats 429, 5xx and redirects as transient, and other 4xx responses as permanent. Redirects are not followed. The response body can change that classification: an explicit validation rejection can make a server error permanent, and an explicit rejection in a 2xx body is classified by its reason. A successful status alone does not override a receiver saying it did not apply the change. The fast backoff doubles its base delay and adds random jitter. These are configured eligibility delays, not promised delivery times:

Scheduled delay after a classified transient failure

Failed attemptConfigured delay before the next attemptTier
160–120 secondsFast
2120–180 secondsFast
3240–300 secondsFast
4480–540 secondsFast
51 hourSlow
63 hoursSlow
712 hoursSlow
The worker reschedules an eligible retry; scan and queue timing can make it run later than the delay shown. Fix a permanent configuration or payload error before requesting another publish. Use Publishing Errors & Retries for recovery steps, and inspect the actual error rather than assuming every failure is temporary.

Why your receiver must be idempotent

A receiver can save an article and then lose its response before the sender receives it. A retry may deliver that article again. Keep a unique blog_id mapping and use an upsert or equivalent transactional update. Do not create a fresh CMS record simply because another request arrived. Scheduled webhook payloads include idempotency_key and publish_attempt. The key combines the blog ID with the stored external post ID, or new before that external ID exists. It does not change just because the title or body changes. publish_attempt is an attempt counter, not a revision number. Manual publishing and Sync omit these retry fields in the paths described by the field reference. This illustrative pair shows why permanently discarding a previously seen key can lose a later edit:
Both requests refer to one article but ask for different writes. Record delivery metadata for diagnostics without using key equality alone to suppress every subsequent update. Serialize writes per article where needed, and define how repeated or out-of-order updates are handled. An upsert prevents duplicate article identities only when your storage constraints and write logic enforce that policy.

How theStacc itself avoids duplicates (direct CMS integrations)

Direct CMS connectors have their own recovery lookups. WordPress and Ghost retry paths can reuse a post found by slug when its title matches and its creation time falls inside the lookup window. The fast-tier window is 35 minutes; it expands cumulatively for slow retries. These are conditional recovery checks, including a retry after a stale WordPress post ID, rather than a lookup before every ordinary update. Shopify checks recent articles by handle. Its collision fallback handle includes the blog ID; the plain-handle branch checks the title when supplied and rejects a parsed creation date older than 24 hours. An inconclusive lookup does not prove the earlier write failed. Do not treat these heuristics as a duplicate-prevention guarantee or copy them as a webhook receiver contract. A stable blog_id mapping gives your receiver an explicit article identity.

Respond fast, do heavy work async

If image processing or a rebuild would make the request slow, acknowledge after the article write or a durable handoff succeeds, then run the remaining work asynchronously. Persist the job and its article association before returning success. An in-memory task started after acknowledgement is not a durable handoff. Define the job’s failure policy: retry failed work, keep error logs, and avoid saying the public page is ready while a rebuild or media job is pending. Return the actual stored CMS ID and known public URL when available. A supported HTTP response acknowledges the request; it does not establish that the article, images or cache update appeared on the live website.