Webhooks: andere Systeme benachrichtigen
Bei Änderungen an Einträgen, Seiten, Menüs oder dem Theme automatisch eine Adresse aufrufen: Website sofort aktualisieren, Builds auslösen, Signatur prüfen, Zustellungen nachverfolgen.
Worum es geht
Ein Webhook ruft bei einem Ereignis in Inhalte – etwa „Seite veröffentlicht“ – automatisch eine Adresse auf. Der häufigste Zweck: Ihre Website erfährt sofort von einer Änderung und zeigt sie ohne Wartezeit an. Ebenso können Sie einen Neuaufbau bei Ihrem Hosting-Anbieter auslösen oder ein eigenes System informieren.
Voraussetzungen
- Recht Einstellungen verwalten.
- Eine öffentlich erreichbare Adresse (
httpoderhttps). Adressen im internen Netz (z.B.localhostoder private IP-Bereiche) werden aus Sicherheitsgründen nicht beliefert.
Einen Webhook erstellen
- Öffnen Sie Webhooks und klicken Sie auf Webhook erstellen.
- Für die sofortige Aktualisierung einer Website aus den Scorebase-Vorlagen klicken Sie bei Next.js Revalidate auf Vorlage nutzen. Die passenden Ereignisse (Seiten, Menüs, Theme) werden gewählt.
- Füllen Sie aus:
| Feld | Bedeutung |
|---|---|
| Name | Frei wählbar, z.B. „Website aktualisieren“ |
| URL | Die Zieladresse |
| Secret (optional) | Geheimnis zum Signieren; wird verschlüsselt gespeichert |
| Events | Mindestens ein Ereignis (siehe unten) |
| Collection-Beschränkung | Nur Ereignisse dieser Collections. Leer = alle |
| Umgebung | Nur Ereignisse dieser Umgebung, oder Alle Umgebungen |
| Aktiv | Webhook sofort scharfschalten |
- Klicken Sie auf Erstellen und prüfen Sie mit Testen, ob die Adresse antwortet („Test erfolgreich (Status 200)“).
Die Ereignisse
| Bereich | Ereignisse |
|---|---|
| Einträge | entry.created, entry.updated, entry.submitted_for_review, entry.approved, entry.rejected, entry.published, entry.unpublished, entry.archived, entry.deleted |
| Medien | media.uploaded, media.deleted |
| Collections | collection.created, collection.changed, collection.deleted |
| Seiten | page.created, page.updated, page.published, page.unpublished, page.deleted |
| Menüs | menu.created, menu.updated, menu.deleted |
| Theme | theme.updated |
| Umgebungen | environment.cloned, environment.promoted |
| Pflege als Code | schema.pushed, blocks.pushed, layouts.pushed, theme.pushed, pages.pushed, menus.pushed |
Was beim Empfänger ankommt
Scorebase sendet einen POST mit JSON:
{
"event": "page.published",
"organizationId": "…",
"timestamp": "2026-09-29T08:15:00.000Z",
"data": { "…": "je nach Ereignis" }
}Kopfzeilen:
| Kopfzeile | Inhalt |
|---|---|
Content-Type |
application/json |
X-Hcms-Event |
Name des Ereignisses |
X-Hcms-Signature |
Nur mit Secret: sha256= gefolgt von der HMAC-SHA256-Signatur des unveränderten Bodys, hexadezimal |
User-Agent |
Kennung des Absenders |
Signatur prüfen
import crypto from "node:crypto"
export function istEcht(rohBody: string, signatur: string | null, secret: string) {
if (!signatur) return false
const erwartet = "sha256=" + crypto.createHmac("sha256", secret).update(rohBody).digest("hex")
const a = Buffer.from(erwartet)
const b = Buffer.from(signatur)
return a.length === b.length && crypto.timingSafeEqual(a, b)
}Prüfen Sie die Signatur immer über den rohen Body, bevor Sie ihn als JSON lesen.
Sonderfall: Aktualisierungs-Webhook der Vorlagen
Endet die URL auf /api/revalidate, sendet Scorebase kein JSON, sondern ruft die Adresse mit ?secret=<Secret>&tag=<Tag> auf. Das Secret muss dem REVALIDATE_SECRET Ihrer Website entsprechen. Die Tags benennen, was sich geändert hat: page:<pfad> für Seiten, menu:<key> für Menüs, theme für das Theme und ein Collection-Tag für Einträge und Collections. Die Vorlagen verwenden dieselben Tags beim Zwischenspeichern und erneuern so genau die betroffenen Seiten.
Zustellung, Wiederholung und Abschaltung
- Eine Zustellung gilt als erfolgreich, wenn der Empfänger innerhalb von 10 Sekunden mit einem Status 200 bis 299 antwortet.
- Schlägt sie fehl, versucht Scorebase es mit wachsendem Abstand erneut, insgesamt bis zu fünfmal.
- Nach 15 Fehlschlägen in Folge wird der Webhook automatisch deaktiviert und mit Auto-deaktiviert markiert. Beheben Sie die Ursache und schalten Sie ihn in der Liste wieder ein.
In der Liste sehen Sie je Webhook Name, URL, Events, Fehler und Status. Über Zustellungen öffnen Sie das Protokoll mit Status (Erfolgreich, Fehlgeschlagen, Retry ausstehend), Ereignis, Versuch, Zeitpunkt und Fehler. Mit Erneut senden stellen Sie eine Zustellung noch einmal zu. Zustellungen werden 90 Tage aufbewahrt.
Über das Stift-Symbol ändern Sie Name, URL, Ereignisse und Secret. Lassen Sie das Secret leer, bleibt das gespeicherte erhalten. Der Schalter in der Liste aktiviert oder deaktiviert einen Webhook, das Papierkorb-Symbol löscht ihn.
Wenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
| Testen meldet „Test fehlgeschlagen (Status 401)“ | Das Secret stimmt nicht mit dem der Website überein | Secret angleichen; bei den Vorlagen ist es REVALIDATE_SECRET |
| „Test fehlgeschlagen (Status —)“ | Adresse nicht erreichbar, im internen Netz oder zu langsam | Adresse im Browser prüfen; öffentliche Adresse verwenden |
| Die Website aktualisiert sich trotzdem nicht | Ereignis nicht gewählt, Webhook auf eine andere Umgebung beschränkt, oder die Website nutzt andere Tags | Ereignisse und Umgebung prüfen; bei eigener Website die Tags abgleichen |
| Webhook ist Auto-deaktiviert | Zu viele Fehlschläge in Folge | Ursache im Protokoll Zustellungen ansehen, beheben, wieder einschalten |