Wir erweitern aktiv die Unterstützung für Webhooks.Gerade eingeführt: automatische Wiederholungen mit exponentiellem Backoff — fehlgeschlagene Lieferungen werden jetzt bis zu 5 Mal innerhalb von 30 Minuten erneut versucht.Demnächst verfügbar:
- Teamweite Standard-Webhook-URLs
- Kryptografische Signaturen zur Überprüfung der Nutzlast
Übersicht
Webhooks liefern Echtzeit-HTTP-POST-Benachrichtigungen an deinen Server, wenn lang andauernde Operationen abgeschlossen sind. Anstatt den Status abzufragen, erhält deine Anwendung sofortige Updates.Anwendungsfälle
Asynchrone Verarbeitung
Lass dich benachrichtigen, wenn Batches oder Crawls abgeschlossen sind, anstatt den Status abzufragen
Pipeline-Auslöser
Automatisches Auslösen der nachgelagerten Verarbeitung, wenn Daten bereit sind
Benachrichtigungen
Sende Benachrichtigungen an Slack, E-Mail oder andere Systeme bei Abschluss
Datenabgleich
Halte deine Datenbank mit den Olostep-Ergebnissen synchron
Unterstützte Ereignisse
batch.completed
batch.completed
Wird ausgelöst, wenn ein Batch die Verarbeitung abgeschlossen hat (alle Elemente abgeschlossen oder fehlgeschlagen).
crawl.completed
crawl.completed
Wird ausgelöst, wenn ein Crawl abgeschlossen ist und alle entdeckten Seiten verarbeitet wurden.
Einrichten von Webhooks
Übergebewebhook, wenn du eine Ressource erstellst. Diese URL erhält die Abschlussbenachrichtigung.
Parametername: Der kanonische Parameter ist
webhook. Zur Rückwärtskompatibilität wird auch webhook_url als Alias akzeptiert.Webhook-Nutzlast
Alle Webhook-Nutzlasten folgen einer einheitlichen Umschlagstruktur:Umschlagfelder
| Feld | Beschreibung |
|---|---|
id | Ereignis-ID — gleich bei allen Wiederholungsversuchen |
object | Ereignistyp (z.B. event.batch.completed) |
timestamp | Wann dieser Lieferungsversuch gesendet wurde (Epoch ms) |
delivery_attempt | Aktueller Versuch / maximale Versuche (z.B. 1/5, 3/5) |
data | Die tatsächlichen Ressourcendaten (gleiches Format wie API-Antwort) |
Wiederholungsverhalten
Fehlgeschlagene Webhook-Lieferungen werden automatisch mit exponentiellem Backoff über ein 30-minütiges Fenster erneut versucht:| Versuch | Verzögerung vor dem Versuch | Kumulative Zeit |
|---|---|---|
| 1 | Sofort | 0 min |
| 2 | ~2 min | ~2 min |
| 3 | ~4 min | ~6 min |
| 4 | ~7 min | ~13 min |
| 5 | ~15 min | ~28 min |
Timeout pro Anfrage: 30 Sekunden
Was als Erfolg zählt
Dein Endpunkt muss innerhalb von 30 Sekunden einen2xx-Statuscode zurückgeben. Jede andere Antwort löst einen erneuten Versuch aus.
| Antwort | Ergebnis |
|---|---|
200 OK | ✅ Geliefert |
201 Created | ✅ Geliefert |
301 Redirect | ❌ Erneut versuchen (wir folgen keinen Weiterleitungen) |
400 Bad Request | ❌ Erneut versuchen |
500 Server Error | ❌ Erneut versuchen |
| Timeout (>30s) | ❌ Erneut versuchen |
| Verbindung abgelehnt | ❌ Erneut versuchen |
Best Practices
Schnell antworten, asynchron verarbeiten
Schnell antworten, asynchron verarbeiten
Gib sofort
200 OK zurück und verarbeite den Webhook asynchron. Wenn deine Verarbeitung länger als 30 Sekunden dauert, versuchen wir es erneut — was zu doppelten Lieferungen führt.Idempotente Handler implementieren
Idempotente Handler implementieren
Verwende das
id-Feld zur Deduplizierung. Speichere verarbeitete Ereignis-IDs und überspringe Duplikate.Webhook-Empfänge protokollieren
Webhook-Empfänge protokollieren
Protokolliere alle Webhook-Empfänge zur Fehlersuche. Füge die Ereignis-ID, den Zeitstempel und das Verarbeitungsergebnis ein.
HTTPS-Endpunkte verwenden
HTTPS-Endpunkte verwenden
Verwende immer HTTPS für Webhook-Endpunkte. HTTP-Endpunkte sind anfällig für Abhören und Man-in-the-Middle-Angriffe.
Fehlerbehebung
Keine Webhooks empfangen
Keine Webhooks empfangen
- Überprüfe, ob der
webhook-Parameter in deiner Anfrage enthalten war - Überprüfe, ob dein Endpunkt öffentlich zugänglich ist (nicht localhost)
- Überprüfe die Serverprotokolle auf eingehende Anfragen
- Stelle sicher, dass du einen
2xx-Statuscode zurückgibst
Doppelte Webhooks empfangen
Doppelte Webhooks empfangen
Dies ist bei Wiederholungen zu erwarten. Implementiere eine idempotente Verarbeitung mit dem
id-Feld:Webhooks laufen ab
Webhooks laufen ab
Dein Endpunkt muss innerhalb von 30 Sekunden antworten. Verarbeite Webhooks asynchron:
Demnächst verfügbar
Team-Standard-URL
Konfiguriere eine Standard-Webhook-URL in deinen Kontoeinstellungen. Alle Anfragen verwenden diese URL, es sei denn, sie wird überschrieben.
Signaturüberprüfung
Kryptografische Signaturen (HMAC-SHA256) zur Überprüfung, dass Webhook-Nutzlasten von Olostep stammen.
Möchtest du frühzeitig Zugang zu diesen Funktionen erhalten? Kontaktiere uns unter info@olostep.com oder tritt unserer Slack-Community bei.