Een backlinkcontrole bij publicatie, stap voor stap
Eén webhook, één HTTP-call, één beslissing. Dit runbook leidt een headless CMS-team door de hook, de calls en de foutscenario's.
Contentin research team ·
Bepaal wat de gate mag doen
Een backlinkcontrole binnen een releaseflow is een kleine klus. Houd het klein. Het moeilijke deel is bepalen wat het antwoord mag veranderen, omdat een linkgrafiek die maandelijks ververst, geen pagina op zichzelf kan blokkeren.
We raden aan dat de gate waarschuwt, logt en de build laat doorgaan. Standaardinstellingen kunnen veranderen. Harde blokkades horen bij dingen die jij beheert, zoals gebroken markup of een ontbrekende canonical-tag. Linkdata is een signaal, en signalen veranderen.
Schrijf het op. Doe dat voordat je gaat coderen. Een beleid van één regel zoals "editor waarschuwen, entry taggen, deploy nooit stoppen" bespaart een lang debat om 18.00 uur op een releasedag. Het vertelt ook de volgende engineer welke fouten opzettelijk waren en welke bugs, wat belangrijker is dan het lijkt. Beoordeel het elk kwartaal.
Zes stappen van publicatieknop tot opgeslagen notitie
1
Kies de trigger
Abonneer je op het publicatie-evenement van je CMS. Contentful, Sanity en Strapi kunnen een URL bellen die jij beheert wanneer een entry wordt gepubliceerd, en Storyblok en Payload bieden ook webhooks of hooks. Filter op de contenttypes die outbound of canonical URLs bevatten.
2
Reduceer de URL tot een domein
De API verwacht een domein in q, dus https://www.example.com/blog/post?x=1 moet eerst worden gereduceerd tot example.com. Bepaal één keer hoe je omgaat met www, en test één echt domein met de gratis domain-actie voordat je iets bouwt.
3
Roep eerst de gratis actie aan
overview kost niets. Als het resultaat dun is, is het domein misschien nieuw of gewoon niet bekend in onze index. Dat is geen bewijs van iets slechts.
4
Gebruik credits alleen wanneer een regel activeert
Wanneer je regel zegt "kijk nader", roep dan backlinks aan met per=100. Het kost 2 credits, ongeacht het aantal rijen, dus vraag om een bruikbare pagina met rijen in plaats van tien kleine.
5
Schrijf een notitie, geen ruwe JSON
Sla een korte conclusie op in een eigen veld, plus de datum van de controle. Ruwe antwoorden laten entries groeien en verouderen snel, omdat de index elke maand verandert.
6
Faal zacht
HTTP 401 betekent dat de key ontbreekt of fout is, dus alerteer een mens. HTTP 402 betekent dat de credits op zijn. Elke andere fout: log het, sla de controle over, laat de publicatie doorgaan.
Waar de key zit en wat een 402 moet doen
Elke betaalde call bevat je key, hetzij in de querystring hetzij in een Bearer-header. Geef de voorkeur aan de header. Een querystring kan in serverlogs en proxytraces terechtkomen, terwijl een header daar meestal buiten blijft.
Sla de key op als een secret in je hostingplatform, nooit in de entry zelf. Editors kunnen elk veld lezen dat ze kunnen openen, maar de omgeving van een functie is meestal alleen zichtbaar voor de mensen die deploys beheren.
Waar moet de key zitten?
Een key die lekt kan het saldo op je account leegspenden, dus behandel het als een wachtwoord. Houd het buiten de repository en buiten de CMS, en draai het om als een logfile het ooit in plaintext laat zien.
Tag je eigen logs met de naam van de hook. Zo is het verbruik eenvoudig terug te voeren op één functie, zelfs wanneer meerdere hooks hetzelfde account delen.
Kan een no-code tool de call doen?
Ja, wanneer de tool een eenvoudige HTTP-request-stap heeft. Veel automatiseringsbouwers kunnen een GET versturen met een querystring en de JSON teruglezen, dus de gratis overview-actie vereist helemaal geen code.
Begin alleen met de gratis acties. Een flow die activeert bij elke draft-save kan credits sneller verbruiken dan een editor merkt, dus voeg een betaalde stap toe zodra de gratis calls een tijdje rustig zijn verlopen.
Wat moet een 402 triggeren?
Een 402 betekent dat het saldo leeg is. Het zegt niets over de pagina. Sla de betaalde controle over, log het evenement en stuur één alert naar degene die het account vult, laat de publicatie dan doorgaan.
Stel een saldoalarm in op een niveau ver boven nul, zodat de waarschuwing aankomt terwijl er nog tijd is om bij te vullen. Een retry-loop helpt hier niet, omdat elke call op dezelfde manier faalt totdat iemand credit toevoegt. De kostentabel bevat de cijfers.
Test de twee calls vanaf een terminal
Voer deze één keer uit tegen een domein dat je kent, voordat de hook het voor je doet. Lees het veld _credits in het tweede antwoord.
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"
Welk domein gaat in de q-parameter
De API verwacht een naakt domein in q, dus een volledige URL moet eerst worden gereduceerd. Schrijf die reductie één keer, in één functie. Test het daarna op echte URLs.
Relatieve links en ontbrekende schemes zijn de gevallen die een hook meestal laten falen. Een reductie die werkt op schone voorbeelden, kan nog steeds falen op de rommelige URLs die een editor om 17.00 uur plakt.
Verandert www het antwoord?
Dat kan, en de eerlijke manier om erachter te komen is het vragen. Voer de gratis domain-actie uit op beide vormen van één site die je kent, en vergelijk de twee antwoorden naast elkaar.
Welke regel je ook kiest, schrijf hem dan in een code-commentaar zodat de volgende engineer niet hoeft te raden. Een commentaar kost niets en bespaart later een lang debat.
Hoe zit het met redirects en subdomeinen?
Stuur de host die je lezers daadwerkelijk bezoeken, niet de link die een editor jaren geleden plakte. Als die link redirect, reduceer dan het eindadres en negeer de tussenstop.
Een blog op een eigen subdomein is een afweging. Bepaal van tevoren of het alleen wordt gecontroleerd of samen met het bovenliggende domein, en schrijf die keuze neer naast de regel.
Pre-release checklist voor de hook
De hook activeert alleen bij publicatie, niet bij elke draft-save
De URL wordt gereduceerd tot een naakt domein voordat de call wordt gedaan
Gratis acties lopen eerst en credits worden alleen verbruikt bij een vlag
Een 401 en een 402 hebben elk hun eigen alert en hun eigen bericht
Er is een timeout ingesteld, zodat een trage API een editor nooit blokkeert
De opgeslagen notitie bevat een datum, zodat niemand het verwarren met live data
Dezelfde entry die twee keer wordt gepubliceerd, wordt niet twee keer gefactureerd (zie de mytheslijst)
Iemand heeft de kostentabel gelezen voor je maandelijkse volume
Wat loggen, en wat blijft buiten de entry
Een logregel voor elke overgeslagen controle is het goedkoopste audit trail dat je kunt bouwen. Registreer de entry ID, het domein dat je hebt verzonden, de statuscode en of een betaalde stap is uitgevoerd. Meestal is dat genoeg.
De opgeslagen notitie blijft kort en gedateerd, zoals de stappen hierboven zeggen. Volledige antwoorden horen in je eigen logs, als ze ergens horen, omdat ze groot zijn en snel verouderen.
Welke velden horen bij een logregel?
Begin met de entry ID en de publish-versie. Een herhaalde webhook verschijnt dan als hetzelfde paar twee keer, wat precies is wat je wilt zien.
Voeg het domein, de actienaam, de statuscode en de tijd toe waarop de call begon. Laat de key zelf weg, omdat een log die de key bevat een tweede plek wordt waar secrets leven.
Hoelang moet een opgeslagen notitie leven?
Zolang de entry bestaat, tenzij een nieuwere controle hem vervangt. Wat telt is dat een lezer kan zien hoe oud de notitie is, omdat een notitie van maanden geleden als live data overkomt.
De score field guide toont de vier velden die we voor die notitie suggereren, inclusief de datum.
Test de hook op staging voordat je lanceert
Voer deze vier controles uit voordat iemand op de hook gaat vertrouwen.
1
Herhaal één eerdere publicatie
Activeer de hook met een kopie van een entry die je al hebt gepubliceerd. Vergelijk de opgeslagen notitie met wat je verwachtte, en bevestig dat dezelfde entry niet twee keer is gefactureerd.
2
Probeer een recent geregistreerd domein
Gebruik een partnerdomein dat nieuw voor je is. Een leeg of dun antwoord moet worden opgeslagen als onbekend, niet als een fout, en de notitie moet dat in duidelijke woorden zeggen.
3
Forceer een 402 opzettelijk
Voer de hook uit met een key op een testaccount waarvan je het saldo hebt leeggehaald. Bevestig dat de skip, de logregel en het alert allemaal activeren, en dat de publicatie de build nog steeds bereikt.
4
Lees het bericht dat de editor ziet
Vraag iemand buiten het team om de foutmelding hardop te lezen. Als ze niet kunnen zeggen wat ze als volgende moeten doen, herschrijf het bericht voordat de releasedag aanbreekt. De post-mortem toont wat een vaag bericht één verzonnen team kostte.
Wat de hook niet kan zien
Onze index ververst ongeveer één keer per maand. Een link die na de laatste ververstering is toegevoegd, verschijnt niet, en een link die sindsdien is verwijderd, kan nog steeds verschijnen. Voor bewijs van dezelfde dag gebruik je het Links-rapport in Google Search Console.
