Webhooks

HMAC-signed callbacks on job state changes.

Setup

Register an endpoint from Settings → Webhooks. We'll generate a signing secret and POST a JSON body to your URL whenever a subscribed event fires.

Events

Event	Fires
`job.completed`	All URLs in a job have been processed
`job.failed`	Job exited with an error
`job.cancelled`	Job was manually cancelled

Signature verification

Each delivery includes X-Scrape-Signature: t=TIMESTAMP,v1=HEX. Compute HMAC-SHA256(secret, "TIMESTAMP." + body) and constant-time compare:

filed under · python.python

import hmac, hashlib

def verify(secret: str, signature_header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    ts, sig = parts["t"], parts["v1"]
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)

Retries

Failed deliveries (non-2xx, timeout) retry with exponential backoff up to 5 times over ~30 minutes. Permanent failures show in Settings → Webhooks → Recent deliveries.

← PREVIOUS

Authentication

Tier escalation

Event

Fires

job.completed

All URLs in a job have been processed

job.failed

Job exited with an error

job.cancelled

Job was manually cancelled

Signature verification

Each delivery includes X-Scrape-Signature: t=TIMESTAMP,v1=HEX. Compute HMAC-SHA256(secret, "TIMESTAMP." + body) and constant-time compare:

filed under · python.python

import hmac, hashlib

def verify(secret: str, signature_header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    ts, sig = parts["t"], parts["v1"]
    expected = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(sig, expected)