Wie funktionieren API-Webhooks?

Über einen Webhook teilt UtilitySEO Ihrem Server mit, wenn ein Scan fertig ist oder fehlschlägt, statt dass Ihre Software immer wieder nachfragen muss. Sie richten pro Projekt einen über die API ein, mit PUT /webhook und einer https-Adresse. Danach senden wir innerhalb von etwa einer Minute nach jedem Scan-Ende eine kurze Nachricht an diese Adresse, signiert, damit Sie prüfen können, dass sie von uns kommt.

Das Bild zeigt die englische Ansicht. Übersetzte Bilder folgen in Kürze.

#Einrichten

Senden Sie Folgendes mit Ihrem API-Schlüssel (siehe die UtilitySEO-API):

PUT /api/v1/webhook
{ "url": "https://dashboard.example.com/hooks/utilityseo", "enabled": true }

• Die Adresse muss https verwenden, auf dem Standardport liegen und im öffentlichen Internet erreichbar sein. Private und interne Adressen werden abgelehnt und vor jeder Zustellung erneut geprüft.
• Die Antwort enthält ein Signatur-Geheimnis. Es wird nur in diesem Moment angezeigt: Bewahren Sie es sicher auf Ihrem Server auf.
• GET /webhook zeigt den Webhook und seine letzte Zustellung, nie das Geheimnis. DELETE /webhook entfernt ihn.
• Senden Sie "rotateSecret": true, um ein neues Geheimnis zu bekommen. Ein neues wird auch ausgestellt, wenn sich die Adresse ändert.

#Was wir senden

Für jeden Scan des Projekts, ob in der App oder über die API gestartet, der fertig wird oder fehlschlägt:

{ "event": "scan.finished", "scanId": "site_812", "projectId": 27, "type": "site", "score": 78, "finishedAt": "..." }

event ist scan.finished oder scan.failed (dann ist score leer). Mit scanId rufen Sie die Ergebnisse ab.

#Prüfen, ob die Nachricht von uns kommt

Jede Nachricht enthält einen Header X-UtilitySEO-Signature: t= mit einer Zeit in Sekunden und v1= mit einer Signatur. So prüfen Sie sie:

1. Nehmen Sie den Rohinhalt genau so, wie er angekommen ist, bevor Sie ihn als JSON einlesen.
2. Berechnen Sie mit Ihrem Signatur-Geheimnis einen HMAC-SHA256 aus der Zeit, einem Punkt und dann dem Inhalt.
3. Vergleichen Sie das Ergebnis mit v1.
4. Lehnen Sie die Nachricht ab, wenn die Zeit mehr als 5 Minuten von Ihrer Uhr abweicht.

Weil die Zeit Teil der Signatur ist, kann eine kopierte Nachricht später nicht erneut abgespielt werden. Ihr Entwickler kann fertigen Beispielcode bei support@utilityseo.com anfordern.

#Antwort, Wiederholungen und Abschalten

• Antworten Sie innerhalb von 10 Sekunden mit einem beliebigen 2xx-Status. Weiterleitungen werden nicht verfolgt.
• Alles andere wird nach 1, 5 und 30 Minuten erneut versucht.
• Wenn 3 Zustellungen hintereinander bei allen Wiederholungen fehlschlagen, wird der Webhook abgeschaltet. Senden Sie PUT /webhook mit "enabled": true, um ihn wieder einzuschalten.
• Gelegentlich kann eine Nachricht doppelt ankommen. Der Header X-UtilitySEO-Delivery ist bei jeder Wiederholung gleich; nutzen Sie ihn oder scanId, um Doppelte zu ignorieren.

#Häufige Fragen

#Kann ich mehr als einen Webhook haben?

Einen pro Projekt. Wenn die Nachricht an mehrere Stellen gehen soll, lassen Sie Ihren Server sie weiterreichen.

#Kann ich einen Webhook in der App einrichten?

Im Moment nicht. Webhooks werden über die API eingerichtet.

#Wie lange speichern Sie die Zustellprotokolle?

Zustellprotokolle werden 90 Tage lang aufbewahrt.