Webhooks

ExtentAPI peut vous notifier en push à chaque transition d’état (job terminé, extraction prête, paiement validé…). Plus rapide que le polling, plus économe en crédits, et signé HMAC pour vérifier l’authenticité.

Enregistrer un endpoint

curl -X POST https://orchestrator.extentapi.example/v1/scraper/webhooks \
  -H "x-api-key: ek_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.exemple.fr/hooks/extentapi",
    "events": ["job.completed", "job.failed"],
    "secret": "auto"
  }'

Réponse :

{
  "id": "wh_01H...",
  "url": "https://api.exemple.fr/hooks/extentapi",
  "secret": "whsec_...",
  "events": ["job.completed", "job.failed"]
}

⚠️ Le secret est retourné une seule fois. Stockez-le côté votre service — il sert à vérifier la signature.

Format des deliveries

Chaque event est posté avec :

POST /hooks/extentapi HTTP/1.1
Content-Type: application/json
x-extentapi-event: job.completed
x-extentapi-event-id: evt_01H...
x-extentapi-timestamp: 1716288000
x-extentapi-signature: t=1716288000,v1=4f2a8b...

Corps :

{
  "event": "job.completed",
  "data": {
    "jobId": "job_01H...",
    "status": "completed",
    "completedAt": "2026-05-21T10:35:12.000Z"
  }
}

Vérifier la signature

import crypto from "node:crypto";

function verify(req, secret) {
  const sig = req.headers["x-extentapi-signature"];
  const ts = req.headers["x-extentapi-timestamp"];
  const [, , v1] = sig.split(/[=,]/);
  const payload = `${ts}.${JSON.stringify(req.body)}`;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Refusez toute signature plus vieille que 5 minutes (anti-replay).

Retry et delivery

• À chaque échec (!= 2xx), retry avec backoff exponentiel (1 min, 5 min, 15 min, 1 h, 4 h, jusqu’à 24 h).
• Au-delà, le webhook est marqué failed mais conservé pour audit.
• Vous pouvez replay manuellement un webhook via le support (V1).

Events disponibles

Scraper

• job.created, job.completed, job.failed, job.replayed.

Extractor

• extraction.completed, extraction.failed (opt-in).

Billing

• balance.low, balance.depleted.

Pour aller plus loin

• Idempotency — chaque event porte un event-id unique.
• Audit log — toute opération webhook est tracée.