Naar hoofdinhoud gaan
We breiden de ondersteuning voor webhooks actief uit.Zojuist geland: automatische herhalingen met exponentiële backoff — mislukte leveringen worden nu tot 5 keer opnieuw geprobeerd binnen 30 minuten.Binnenkort beschikbaar:
  • Team-brede standaard webhook-URL’s
  • Cryptografische handtekeningen voor payloadverificatie
Wil je vroegtijdige toegang? Neem contact op via info@olostep.com of sluit je aan bij onze Slack-gemeenschap.

​
Overzicht

Webhooks leveren real-time HTTP POST-meldingen aan je server wanneer langdurige operaties zijn voltooid. In plaats van te polleren voor status, ontvangt je applicatie directe updates.

​
Gebruiksscenario’s

Asynchrone Verwerking

Ontvang een melding wanneer batches of crawls zijn voltooid in plaats van te polleren

Pipeline Triggers

Start automatisch downstream-verwerking wanneer gegevens gereed zijn

Waarschuwingen

Stuur waarschuwingen naar Slack, e-mail of andere systemen bij voltooiing

Gegevenssynchronisatie

Houd je database gesynchroniseerd met Olostep-resultaten

​
Ondersteunde Evenementen

Wordt geactiveerd wanneer een batch klaar is met verwerken (alle items voltooid of mislukt).
{
  "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"
  }
}
Wordt geactiveerd wanneer een crawl is voltooid en alle ontdekte pagina’s zijn verwerkt.
{
  "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"
  }
}

​
Webhooks Instellen

Geef webhook door bij het aanmaken van een resource. Deze URL ontvangt de voltooiingsmelding.
Parameternaam: De canonieke parameter is webhook. Voor achterwaartse compatibiliteit wordt webhook_url ook geaccepteerd als alias.
import requests

# Batch voorbeeld
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 voorbeeld
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 Payload

Alle webhook payloads volgen een uniforme envelopstructuur: 
{
  "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
  }
}

​
Envelopvelden

VeldBeschrijving
idEvent ID — hetzelfde bij alle herhalingspogingen
objectType evenement (bijv. event.batch.completed)
timestampWanneer deze leveringspoging is verzonden (epoch ms)
delivery_attemptHuidige poging / max pogingen (bijv. 1/5, 3/5)
dataDe daadwerkelijke resourcegegevens (zelfde formaat als API-reactie)
Gebruik het id veld om webhook leveringen in je ontvanger te dedupliceren. Dezelfde event ID verschijnt in alle herhalingspogingen.

​
Herhalingsgedrag

Mislukte webhook leveringen worden automatisch opnieuw geprobeerd met exponentiële backoff over een venster van 30 minuten:
PogingVertraging Voor PogingCumulatieve Tijd
1Onmiddellijk0 min
2~2 min~2 min
3~4 min~6 min
4~7 min~13 min
5~15 min~28 min
Totale herhalingsvenster: 30 minuten
Timeout per verzoek: 30 seconden

​
Wat telt als succes

Je endpoint moet binnen 30 seconden een 2xx statuscode retourneren. Elke andere reactie triggert een herhaling.
ReactieResultaat
200 OK✅ Geleverd
201 Created✅ Geleverd
301 Redirect❌ Herhalen (we volgen geen redirects)
400 Bad Request❌ Herhalen
500 Server Error❌ Herhalen
Timeout (>30s)❌ Herhalen
Verbinding geweigerd❌ Herhalen

​
Best Practices

Retourneer 200 OK onmiddellijk en verwerk de webhook asynchroon. Als je verwerking langer dan 30 seconden duurt, proberen we opnieuw — wat leidt tot dubbele leveringen.
from queue import Queue
import threading

webhook_queue = Queue()

@app.route('/webhooks/olostep', methods=['POST'])
def handle_webhook():
    # In de rij zetten voor asynchrone verwerking
    webhook_queue.put(request.json)
    
    # Onmiddellijk retourneren
    return 'OK', 200

def process_webhooks():
    while True:
        event = webhook_queue.get()
        # Langzame verwerking gebeurt hier
        process_event(event)

threading.Thread(target=process_webhooks, daemon=True).start()
Gebruik het id veld om te dedupliceren. Sla verwerkte event ID’s op en sla duplicaten over.
processed_events = set()  # Gebruik Redis/DB in productie

def handle_event(event):
    if event['id'] in processed_events:
        return  # Al verwerkt
    
    # Verwerk het event
    process_batch_completed(event['data'])
    
    # Markeer als verwerkt
    processed_events.add(event['id'])
Log alle webhook ontvangsten voor debugging. Inclusief het event ID, timestamp en verwerkingsresultaat.
import logging

@app.route('/webhooks/olostep', methods=['POST'])
def handle_webhook():
    event = request.json
    logging.info(f"Webhook ontvangen: id={event['id']} type={event['object']} poging={event['delivery_attempt']}")
    
    try:
        process_event(event)
        logging.info(f"Webhook verwerkt: id={event['id']}")
    except Exception as e:
        logging.error(f"Webhook mislukt: id={event['id']} fout={e}")
        raise
    
    return 'OK', 200
Gebruik altijd HTTPS voor webhook endpoints. HTTP endpoints zijn kwetsbaar voor afluisteren en man-in-the-middle aanvallen.

​
Problemen Oplossen

  1. Controleer of de webhook parameter in je verzoek is opgenomen
  2. Controleer of je endpoint openbaar toegankelijk is (niet localhost)
  3. Controleer je serverlogs op binnenkomende verzoeken
  4. Zorg ervoor dat je een 2xx statuscode retourneert
Dit is te verwachten tijdens herhalingen. Implementeer idempotente verwerking met behulp van het id veld:
def handle_event(event):
    if already_processed(event['id']):
        return  # Sla duplicaat over
    
    process_event(event)
    mark_processed(event['id'])
Je endpoint moet binnen 30 seconden reageren. Verwerk webhooks asynchroon:
@app.route('/webhooks', methods=['POST'])
def webhook():
    queue.enqueue(process_webhook, request.json)
    return 'OK', 200  # Onmiddellijk reageren

​
Binnenkort Beschikbaar

Team Standaard URL

Stel een standaard webhook URL in in je accountinstellingen. Alle verzoeken zullen deze URL gebruiken tenzij overschreven.

Handtekening Verificatie

Cryptografische handtekeningen (HMAC-SHA256) om te verifiëren dat webhook payloads van Olostep komen.
Wil je vroegtijdige toegang tot deze functies? Neem contact op via info@olostep.com of sluit je aan bij onze Slack-gemeenschap.