One webhook, one HTTP call, one decision. This runbook walks a headless CMS team through the hook, the calls and the failure cases.
Contentin research team ·
Decide what the gate may do
A page backlink check inside a release flow is a small job. Keep it small. The hard part is deciding what the answer is allowed to change, because a link graph that refreshes monthly cannot veto a page on its own.
We suggest the gate warns, logs and lets the build continue. Defaults can change. Hard blocks belong to things you control, such as broken markup or a missing canonical tag. Link data is a signal, and signals drift.
Write it down. Do that before you code it. A one-line policy such as "warn the editor, tag the entry, never stop the deploy" saves a long argument at 6 pm on a release day. It also tells the next engineer which failures were intended and which were bugs, which matters more than it sounds. Review it once a quarter.
Six steps from publish click to stored note
1
Pick the trigger
Subscribe to the publish event of your CMS. Contentful, Sanity and Strapi can call a URL you own when an entry is published, and Storyblok and Payload offer webhooks or hooks too. Filter to the content types that carry outbound or canonical URLs.
2
Reduce the URL to a domain
The API takes a domain in q, so https://www.example.com/blog/post?x=1 has to become example.com first. Decide once how you treat www, and test one real domain on the free domain action before you build anything.
3
Call the free action first
overview costs nothing. If it comes back thin, the domain may be new or simply unknown to our index. That is not proof of anything bad.
4
Spend credits only when a rule fires
When your rule says look closer, call backlinks with per=100. It is 2 credits, whatever the number of rows, so ask for a useful page of rows rather than ten small ones.
5
Write a note, not the raw JSON
Store a short verdict in a field of your own, plus the date of the check. Raw responses bloat entries and age badly, since the index moves every month.
6
Fail soft
HTTP 401 means the key is missing or wrong, so alert a human. HTTP 402 means the credit is gone. Any other error: log it, skip the check, let the publish go through.
Test the two calls from a terminal
Run these once against a domain you know before the hook does it for you. Read the _credits field on the second response.
bash
# free, no key
curl -s "https://contentin.app/api.php?action=overview&q=example.com"
# 2 credits, key in a header
curl -s -H "Authorization: Bearer sk_live_..." \
"https://contentin.app/api.php?action=backlinks&q=example.com&per=100"
Pre-release checklist for the hook
The hook fires on publish only, not on every draft save
The URL is reduced to a bare domain before the call
Free actions run first and credits are spent only on a flag
A 401 and a 402 each have their own alert and their own message
A timeout is set, so a slow API never stalls an editor
The stored note carries a date, so nobody mistakes it for live data
The same entry published twice does not bill twice (see the myth list)
Someone has read the cost table for your monthly volume
What the hook cannot see
Our index refreshes roughly once a month. A link added after the last refresh will not show up, and a link removed since may still appear. For same-day proof, use the Links report in Google Search Console.