How webhooks work
A webhook is CitedSEO telling your code that something published. Each time an article goes live or its live version changes, we post the article to every endpoint you have added, as JSON, signed with that endpoint’s own secret.
It works whatever your site publishes to. A site on WordPress can still add a webhook, to hook its own tools in.
Add an endpoint
Section titled “Add an endpoint”-
In the CitedSEO app, open Settings, then Integrations, then Webhooks.
-
Add your endpoint’s address. It must be
httpsand on the public internet: anhttpaddress,localhostor a private network address is refused. -
Copy the signing secret. It starts with
whsec_and is shown once. Keep it on your server, for example asCITEDSEO_WEBHOOK_SECRET.
Each endpoint has its own secret, and a site can have more than one endpoint. Removing an endpoint in the app stops its posts at once.
What your endpoint does
Section titled “What your endpoint does”-
Read the raw body as text, before any JSON parsing.
-
Verify the signature with your secret. Turn away anything that doesn’t verify.
-
Answer with a
2xxquickly, within 15 seconds. Do slow work after you answer. -
Act on it: rebuild, clear a cache, or store the article. The post carries the whole article. The feed is rebuilt before the post is sent, so a re-read normally sees the new build; if that rebuild failed, the post is still sent and the feed catches up on its next rebuild, so use the article in the post when you need to be sure.
Testing on your own machine
Section titled “Testing on your own machine”An endpoint must be on the public internet, so localhost can’t be added. Use a tunnel (Cloudflare Tunnel, ngrok and similar give you an https address that forwards to your machine) and add the tunnel’s address as an endpoint while you build.