Design a Publishing Webhook for a Custom Website

Define what the receiver promises

A publishing webhook should have a written contract before it has production traffic. Decide whether the receiver creates a draft, updates a record, or makes content live. Define what its acknowledgment means: accepted for processing is different from publicly available. Cloudflare's queue delivery documentation and Web Crypto support are useful infrastructure references, but the article contract remains your application design. For a hypothetical developer-tools company with a custom website, the safest initial contract may accept approved content into a build queue and return a receipt without claiming the build is finished.

Send structured article data

Include a stable article identity, content revision, intended operation, destination identity, and the fields needed to render the page. Keep title, body, description, slug, dates, and media references separate. Version the contract so a future field change does not silently break old receivers. Specify whether the body is Markdown, sanitized HTML, or a structured document. Explain which fields can be absent and what an omitted field means during an update. The developer-tools site should never have to infer whether an empty description requests deletion or simply indicates that no new description was supplied.

Authenticate the event before acting

Use a documented signature scheme and verify the exact signed bytes before trusting the event. Keep shared secrets out of the payload and rotate them through a controlled process. Validate the intended destination after verifying the signature, since authentication does not replace authorization. Enforce reasonable request size and content constraints. The receiver should reject an event for another site even if it was signed by a generally trusted service. Log a safe event identifier and verification outcome so troubleshooting can proceed without exposing secrets or entire private drafts.

Return an actionable receipt

Respond with a stable receipt or remote record identifier after durable acceptance. If processing is asynchronous, offer a status query or callback with clearly defined outcomes. Avoid a success response before anything recoverable has been stored, because a crash would then lose an event the sender believes succeeded. Define how validation failures differ from temporary failures. For the developer-tools example, an unsupported document format should request a corrected submission, while an unavailable build service may justify a delayed retry. A receipt connects those later decisions to the original request.

Test failure and duplicate delivery

Exercise duplicate requests, delayed messages, interrupted processing, and old revisions arriving after new ones. A reliable receiver identifies repeated operations and does not create a second page. It also prevents a stale revision from replacing an approved newer article. Record the final public URL when available and verify that it serves the intended content. Keep an operator path to retry a failed job after fixing configuration. The result is a contract that supports recovery, rather than a fragile endpoint that only works when every request arrives exactly once in the expected order.

Include a sample event and expected response in the receiver documentation, clearly labeled as your own contract. A developer integrating a custom website should be able to test the exchange without generating a real article first.