Zum Hauptinhalt springen
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 von Nutzlasten
Möchten Sie frühzeitig Zugang erhalten? Kontaktieren Sie uns unter info@olostep.com oder treten Sie unserer Slack-Community bei.

​
Überblick

Webhooks liefern Echtzeit-HTTP-POST-Benachrichtigungen an Ihren Server, wenn langwierige Operationen abgeschlossen sind. Anstatt den Status abzufragen, erhält Ihre Anwendung sofortige Updates.

​
Anwendungsfälle

Asynchrone Verarbeitung

Lassen Sie sich benachrichtigen, wenn Stapel oder Crawls abgeschlossen sind, anstatt den Status abzufragen

Pipeline-Auslöser

Lösen Sie automatisch nachgelagerte Verarbeitungen aus, wenn Daten bereit sind

Alarmierung

Senden Sie Benachrichtigungen an Slack, E-Mail oder andere Systeme bei Abschluss

Datenabgleich

Halten Sie Ihre Datenbank synchron mit Olostep-Ergebnissen

​
Unterstützte Ereignisse

Wird ausgelöst, wenn ein Stapel die Verarbeitung abgeschlossen hat (alle Elemente abgeschlossen oder fehlgeschlagen).
{
  "id": "event_a1b2c3d4e5f6g7h8",
  "object": "event.batch.completed",
  "timestamp": 1737570000000,
  "delivery_attempt": "1/5",
  "data": {
    "id": "batch_xyz123",
    "object": "batch",
    "status": "completed",
    "items_total": 100,
    "items_completed": 98,
    "items_failed": 2,
    "created_at": "2024-01-15T10:00:00Z",
    "completed_at": "2024-01-15T10:05:32Z"
  }
}
Wird ausgelöst, wenn ein Crawl abgeschlossen ist und alle entdeckten Seiten verarbeitet wurden.
{
  "id": "event_x9y8z7w6v5u4t3s2",
  "object": "event.crawl.completed",
  "timestamp": 1737570000000,
  "delivery_attempt": "1/5",
  "data": {
    "id": "crawl_abc789",
    "object": "crawl",
    "status": "completed",
    "start_url": "https://example.com",
    "urls_count": 87,
    "max_pages": 100,
    "max_depth": 3,
    "actual_max_depth": 3,
    "start_epoch": 1737569500000,
    "start_date": "2024-01-15"
  }
}

​
Einrichtung von Webhooks

Geben Sie webhook an, wenn Sie eine Ressource erstellen. Diese URL erhält die Abschlussbenachrichtigung.
Parametername: Der kanonische Parameter ist webhook. Zur Abwärtskompatibilität wird auch webhook_url als Alias akzeptiert.
import requests

# Stapelbeispiel
response = requests.post(
    "https://api.olostep.com/v1/batches",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
    json={
        "items": [
            {"url": "https://example.com/page1", "custom_id": "1"},
            {"url": "https://example.com/page2", "custom_id": "2"}
        ],
        "webhook": "https://your-server.com/webhooks/olostep"
    }
)

# Crawl-Beispiel
response = requests.post(
    "https://api.olostep.com/v1/crawls",
    headers={"Authorization": "Bearer <YOUR_API_KEY>"},
    json={
        "start_url": "https://example.com",
        "max_pages": 50,
        "webhook": "https://your-server.com/webhooks/olostep"
    }
)

​
Webhook-Nutzlast

Alle Webhook-Nutzlasten folgen einer einheitlichen Umschlagstruktur: 
{
  "id": "event_a1b2c3d4e5f6g7h8",
  "object": "event.batch.completed",
  "timestamp": 1737570000000,
  "delivery_attempt": "1/5",
  "data": {
    "id": "batch_xyz123",
    "object": "batch",
    "status": "completed",
    "items_total": 100,
    "items_completed": 98,
    "items_failed": 2
  }
}

​
Umschlagfelder

FeldBeschreibung
idEreignis-ID — gleich bei allen Wiederholungsversuchen
objectEreignistyp (z.B., event.batch.completed)
timestampWann dieser Lieferungsversuch gesendet wurde (Epoch ms)
delivery_attemptAktueller Versuch / maximale Versuche (z.B., 1/5, 3/5)
dataDie tatsächlichen Ressourcendaten (gleiches Format wie API-Antwort)
Verwenden Sie das id-Feld, um Webhook-Lieferungen in Ihrem Empfänger zu deduplizieren. Die gleiche Ereignis-ID erscheint in allen Wiederholungsversuchen.

​
Wiederholungsverhalten

Fehlgeschlagene Webhook-Lieferungen werden automatisch mit exponentiellem Backoff innerhalb eines 30-Minuten-Fensters erneut versucht:
VersuchVerzögerung vor dem VersuchKumulative Zeit
1Sofort0 min
2~2 min~2 min
3~4 min~6 min
4~7 min~13 min
5~15 min~28 min
Gesamtes Wiederholungsfenster: 30 Minuten
Timeout pro Anfrage: 30 Sekunden

​
Was als Erfolg zählt

Ihr Endpunkt muss innerhalb von 30 Sekunden einen 2xx-Statuscode zurückgeben. Jede andere Antwort löst einen Wiederholungsversuch aus.
AntwortErgebnis
200 OK✅ Geliefert
201 Created✅ Geliefert
301 Redirect❌ Wiederholen (wir folgen keinen Weiterleitungen)
400 Bad Request❌ Wiederholen
500 Server Error❌ Wiederholen
Timeout (>30s)❌ Wiederholen
Verbindung abgelehnt❌ Wiederholen

​
Beste Praktiken

Geben Sie sofort 200 OK zurück und verarbeiten Sie den Webhook asynchron. Wenn Ihre Verarbeitung länger als 30 Sekunden dauert, werden wir erneut versuchen — was zu doppelten Lieferungen führt.
from queue import Queue
import threading

webhook_queue = Queue()

@app.route('/webhooks/olostep', methods=['POST'])
def handle_webhook():
    # In die Warteschlange für asynchrone Verarbeitung einreihen
    webhook_queue.put(request.json)
    
    # Sofort zurückgeben
    return 'OK', 200

def process_webhooks():
    while True:
        event = webhook_queue.get()
        # Langsame Verarbeitung erfolgt hier
        process_event(event)

threading.Thread(target=process_webhooks, daemon=True).start()
Verwenden Sie das id-Feld zur Deduplizierung. Speichern Sie verarbeitete Ereignis-IDs und überspringen Sie Duplikate.
processed_events = set()  # Verwenden Sie Redis/DB in der Produktion

def handle_event(event):
    if event['id'] in processed_events:
        return  # Bereits verarbeitet
    
    # Ereignis verarbeiten
    process_batch_completed(event['data'])
    
    # Als verarbeitet markieren
    processed_events.add(event['id'])
Protokollieren Sie alle Webhook-Empfänge zur Fehlerbehebung. Schließen Sie die Ereignis-ID, den Zeitstempel und das Verarbeitungsergebnis ein.
import logging

@app.route('/webhooks/olostep', methods=['POST'])
def handle_webhook():
    event = request.json
    logging.info(f"Webhook empfangen: id={event['id']} type={event['object']} attempt={event['delivery_attempt']}")
    
    try:
        process_event(event)
        logging.info(f"Webhook verarbeitet: id={event['id']}")
    except Exception as e:
        logging.error(f"Webhook fehlgeschlagen: id={event['id']} error={e}")
        raise
    
    return 'OK', 200
Verwenden Sie immer HTTPS für Webhook-Endpunkte. HTTP-Endpunkte sind anfällig für Abhören und Man-in-the-Middle-Angriffe.

​
Fehlerbehebung

  1. Überprüfen Sie, ob der webhook-Parameter in Ihrer Anfrage enthalten war
  2. Überprüfen Sie, ob Ihr Endpunkt öffentlich zugänglich ist (nicht localhost)
  3. Überprüfen Sie Ihre Serverprotokolle auf eingehende Anfragen
  4. Stellen Sie sicher, dass Sie einen 2xx-Statuscode zurückgeben
Dies ist während der Wiederholungen zu erwarten. Implementieren Sie idempotente Verarbeitung mit dem id-Feld:
def handle_event(event):
    if already_processed(event['id']):
        return  # Duplikat überspringen
    
    process_event(event)
    mark_processed(event['id'])
Ihr Endpunkt muss innerhalb von 30 Sekunden antworten. Verarbeiten Sie Webhooks asynchron:
@app.route('/webhooks', methods=['POST'])
def webhook():
    queue.enqueue(process_webhook, request.json)
    return 'OK', 200  # Sofort antworten

​
Demnächst verfügbar

Team-Standard-URL

Konfigurieren Sie eine Standard-Webhook-URL in Ihren Kontoeinstellungen. Alle Anfragen verwenden diese URL, es sei denn, sie wird überschrieben.

Signaturverifizierung

Kryptografische Signaturen (HMAC-SHA256), um zu überprüfen, dass Webhook-Nutzlasten von Olostep stammen.
Möchten Sie frühzeitig Zugang zu diesen Funktionen erhalten? Kontaktieren Sie uns unter info@olostep.com oder treten Sie unserer Slack-Community bei.