How it works
Every time an article publishes, Ryze sends one HTTP request to your endpoint:- Method:
POST - Headers:
Authorization: Bearer <your token>,Content-Type: application/json,X-Ryze-Payload-SHA256(the hex SHA-256 of the request body), and aUser-AgentcontainingRyzeBot/1.0 (+https://get-ryze.ai) - Body:
body_html is ready-to-serve HTML, body_markdown is the same article in Markdown, and blocks carries Ryze’s structured rich blocks (TL;DR, stats, FAQ) when the article has them. image.url is a permanently hosted copy of the featured image — save it or hotlink it. primary_keyword and image can be null.
Your endpoint should upsert by slug — if an article with that slug already exists, replace it. Republishing an updated article sends the same slug again, and your upsert is what makes the update land. To make sure the body arrived complete, your endpoint can compare the SHA-256 of the raw body with X-Ryze-Payload-SHA256. If a firewall or bot protection sits in front of your endpoint, allow requests whose user agent contains RyzeBot. Return any 2xx status to confirm. Ryze follows up to three 307/308 redirects to an https:// address on the same domain; any other redirect or non-2xx status is treated as a failure and shown in Ryze with your endpoint’s response.
Step 1 — Build the endpoint on your site
1
Create a POST route
Add an HTTPS endpoint on your site, e.g.
https://yoursite.com/api/articles/webhook. Plain HTTP is not accepted.2
Check the bearer token
Generate a long random token and have the endpoint reject any request whose
Authorization: Bearer header doesn’t match it.3
Save the article
Parse the JSON body, store the article (most receivers save
body_html plus the meta fields) so your site renders it at a stable URL — ideally your blog URL + slug (see below). Upsert by slug and respond 200.Step 2 — Connect in Ryze
On the Integrations page, click Connect on the Custom Webhook card and fill in:- Webhook URL — the endpoint you built, e.g.
https://yoursite.com/api/articles/webhook - Bearer token — the token your endpoint expects (stored encrypted)
- Blog URL — where published articles appear publicly, e.g.
https://yoursite.com/blog
The article’s public link is built as Blog URL + slug (e.g.
https://yoursite.com/blog/example-article-slug). Make sure your site serves articles at that path — Ryze also uses it to periodically verify published pages are still live.What the webhook can and can’t do
- Publishing and updating work fully — every publish and republish is a POST your endpoint upserts.
- Removing an article is not part of the contract. When you delete an article in Ryze, the live copy stays on your site until you remove it there — Ryze tells you this wherever it applies.
- Images: the featured image arrives as a hosted
image.urlyou can save or hotlink. Inline article images are already embedded inbody_html.
Troubleshooting
- “Your webhook endpoint rejected the article (HTTP 401, … bytes sent)…” (or
403) — the bearer token in Ryze doesn’t match what your endpoint checks. Reconnect with the right token. For other statuses, the error ends with your endpoint’s response. If your server rejects large requests (for example413), compare its request size limit with the bytes sent in the error and raise it. - “Your webhook endpoint redirects to … — update the Custom Webhook URL to that address” — your endpoint answered with a redirect Ryze won’t follow (a
301/302, a redirect to a different domain or a non-HTTPS address, or more than three redirects). Point the Webhook URL at the final address. - “Your webhook endpoint could not be reached or did not respond within 30s (… bytes sent) — check that it is online and accepts POST requests” — the endpoint is down, unreachable from the public internet, or not answering within 30 seconds. If the body is large, also check your server’s request size limit against the bytes sent.
- Article publishes but the page 404s — your site isn’t serving the article at
Blog URL + slug; adjust the route or the Blog URL so they match.

