Webhooks gjør ethvert oppstrømssystem om til en utgiver. Signer en nyttelast, POST den, og motoren tilordner den til innhold og bygger på nytt — ingen nøkkelutveksling i forespørselsbanen, fordi signaturen er autentiseringen.
Endepunktet
POST https://your-host/webhooks/{integration}{integration} er en slug du velger når du oppretter integrasjonen — ikke navnet på en tilordner. Hver har sin egen slug, sin egen hemmelighet og én tilordner bak seg, slik at et nettsted kan ha flere: newsroom, docs-sync, partner-feed. Slugger består av små bokstaver, sifre og bindestreker.
php bin/fastsite webhook:create newsroom --site=blog --mapper=autoseoDette skriver ut den fullstendige URL-en og signeringshemmeligheten én gang. Du kan gjøre det samme fra dashbordet, REST API-et eller MCP-verktøyet create_webhook — webhooks er nettstedsomfattende, så ethvert medlem av et nettsted kan administrere dem uten å være administrator.
Signering av en forespørsel
Den rå kroppen leses som den er og verifiseres før noe annet kjører. To overskrifter kreves:
X-Fastsite-Signature: t=<unix>,v1=<hmac_sha256("<t>.<body>", secret)>— den signerte strengen er tidsstempelet, et bokstavelig punktum og de eksakte bytene du sender. Sammenlignes i konstant tid, innenfor et vindu på ±300 sekunder.X-Delivery-Id— unik per levering. Den er vernet mot replay-angrep: en gjentatt id aksepteres med en200og ignoreres stille i stedet for å behandles to ganger.
Signer bytene du faktisk sender. Ny serialisering av JSON mellom signering og sending er den vanlige årsaken til at en signatur ikke lar seg verifisere.
Et konkret eksempel
# body.json er de eksakte bytene du signerer og sender
SECRET="whsec_…"
BODY=$(cat body.json)
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | \
openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
curl -X POST https://your-host/webhooks/newsroom \
-H "X-Fastsite-Signature: t=$TS,v1=$SIG" \
-H "X-Delivery-Id: $(uuidgen)" \
-H "Content-Type: application/json" \
--data-binary @body.jsonHva som returneres
| Kode | Betydning |
|---|---|
| 202 | Akseptert. Registrert og satt i kø. |
| 200 | Duplikat leverings-id — allerede sett, ingenting gjort. |
| 400 | Manglende X-Delivery-Id. |
| 401 | Manglende eller ugyldig signatur. |
| 404 | Ingen slik integrasjon, eller den er deaktivert. |
Endepunktet svarer på millisekunder fordi det bare registrerer og setter i kø. Tilordningen, byggingen og publiseringen skjer i køen etterpå, med nye forsøk og nedtrapping.
Webhooks publiserer; API-et gjør ikke det
Dette er den eneste reelle forskjellen mellom de to inntaksmåtene. Å opprette innhold via REST eller MCP lagrer det og venter på at du publiserer. En webhook-levering kjører tilordneren sin og kobler deretter automatisk en bygging og en publisering — et oppstrømssystem som pusher en artikkel forventer at den er live, ikke klargjort.
Innebygde tilordnere
Tilordnere er kode, ikke konfigurasjonsstrenger. Hver tar en generisk nyttelast og gjør den om til en motorhandling.
| Tilordner | Nyttelast | Gjør |
|---|---|---|
autoseo | {id, title, body_html, slug?, excerpt?, featured_image_url?, author?, seo_title?, seo_description?, status?, published_at?} | Idempotent artikkelinntak, nøklet på id. |
create_post | {title, body_html, slug?, excerpt?, status?, author?, source_ref?} | Tilordner en nyttelast til et innlegg. |
create_page | Samme som over | Tilordner en nyttelast til en side. |
import_media | {url, alt?, decorative?} | Henter en fil via URL (SSRF-beskyttet) inn i biblioteket. |
upsert_component | {handle, type, source_code, css?} | Oppretter eller oppdaterer en komponent. |
autoseo er den du bør bruke med en artikkelrørledning. Den er idempotent på nyttelastens id, slik at ny levering oppdaterer det eksisterende innlegget i stedet for å opprette et nytt. Den adopterer også bilder: fremhevet bilde og alle eksterne <img>-elementer i kroppen hentes inn i mediebiblioteket ditt og skrives om til lokale referanser, med alt-tekst utledet fra tittelen når kilden mangler den. Hvis et bilde ikke kan hentes, droppes bildet og artikkelen publiseres likevel — et ødelagt CDN oppstrøms bør ikke koste deg saken.
For innholdstilordnere er standardverdien for status published. Send source_ref hvis du vil at ny levering skal oppdatere i stedet for å duplisere.
Når noe går galt
Hver levering registreres med sine overskrifter, kropp og utfall, slik at en feil kan inspiseres i stedet for å gå tapt.
php bin/fastsite webhook:list
php bin/fastsite webhook:deliveries --limit=20
php bin/fastsite webhook:replay <delivery-id>En nyttelast som tilordneren ikke kan bruke — manglende id, ingen title, ugyldig JSON — merkes som skipped og forsøkes ikke på nytt, fordi nye forsøk ikke vil rette det. Alt annet som kaster feil, merkes som failed og forsøkes på nytt med nedtrapping. Replay kjører en lagret levering fra de registrerte bytene på nytt, slik at du kan rette en tilordner eller et legitimasjonssett og behandle på nytt uten å be avsenderen prøve igjen.
Hemmeligheter lagres kryptert og kan vises igjen fra dashbordet for å konfigurere en avsender. Foretrekker du å hente fremfor å bli pushet til? REST API-et og MCP-serveren dekker de samme operasjonene.