Aller au contenu principal

Webhooks

Auralith envoie des webhooks HTTP signes HMAC quand des events significatifs se produisent (mass patch termine, drift detecte, approbation accordee, etc.).

Quand l'utiliser​

  • Notifier Slack / PagerDuty / Jira d'une approbation pending.
  • Trigger un job CI quand une migration est appliquee.
  • Logger les drifts dans votre SIEM.

Workflow rapide​

  1. Configuration projet -> Webhooks -> Nouveau webhook.
  2. URL, events souscrits, secret (genere ou fourni).
  3. Tester. Auralith envoie un event webhook.test immediat. Verifiez la reception.
  4. Activer. Les events selectionnes partent en async, avec retry exponentiel en cas d'echec.

Events disponibles​

  • mass_patch.completed (succes ou echec)
  • mass_patch.dry_run.completed
  • seed.run.completed
  • bridge.run.completed
  • anonymize.run.completed
  • drift.detected
  • approval.requested
  • approval.decided
  • access_request.requested
  • access_request.approved
  • migration.applied

Format payload​

{
  "id": "evt_01H...",
  "type": "mass_patch.completed",
  "occurred_at": "2026-04-24T10:30:00Z",
  "project_id": "...",
  "data": {
    "patch_id": "...",
    "status": "success",
    "rows_affected": 42158,
    "duration_ms": 12340
  }
}

Signature HMAC​

Chaque requete porte un header :

X-Auralith-Signature: t=1714123200,v1=<hex_hmac_sha256>
X-Auralith-Event-Id: evt_01H...

Le v1 est HMAC-SHA256(secret, "{t}.{body}"). Verifier cote receiver :

import hmac, hashlib

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

Retry et delivery​

  • Retry : 5 tentatives, backoff exponentiel (1s, 5s, 25s, 2min, 10min).
  • Timeout : 10s par tentative.
  • WebhookDelivery : chaque tentative est trackee. Visible dans Configuration projet -> Webhooks -> [webhook] -> Deliveries.
  • At-least-once : l'event peut arriver plusieurs fois si le receiver repond non-2xx. Idempotency-key = X-Auralith-Event-Id.

Pieges courants​

  • Replay attack : verifier t (timestamp) et rejeter si > 5 min vieux.
  • Endpoint lent : Auralith timeout a 10s. Si votre receiver fait du travail synchrone long, accepter rapidement (202) puis traiter en async.
  • Body modifie par proxy : si un proxy compresse / decompresse le body, la signature ne match plus. Verifier avant deployment.

Voir aussi​