Webhooks

Les webhooks Anonyx envoient une requête HTTP POST à votre serveur dès qu'un événement survient sur un projet d'anonymisation. C'est le mécanisme push recommandé pour réagir en temps réel à la fin d'un run, à un échec ou à une annulation, sans avoir à interroger l'API.

Chaque webhook est rattaché à un projet : un projet possède sa propre liste de webhooks indépendante, avec ses URL cibles, son secret et sa sélection d'événements.

Création et gestion d'un webhook

Vous pouvez créer et gérer les webhooks d'un projet de deux manières complémentaires.

Depuis l'interface

Depuis votre tableau de bord, ouvrez le projet concerné puis l'onglet Webhooks pour créer, activer, tester ou supprimer une intégration sans écrire de code.

/projects/{projectId}/webhooks

Depuis l'API REST

Les endpoints POST /webhooks, PUT /webhooks/{id}, DELETE /webhooks/{id} et POST /webhooks/{id}/test permettent l'automatisation complète.

Voir la référence API →

L'accès aux webhooks est conditionné par votre abonnement.

Événements supportés

Lors de la création d'un webhook, vous sélectionnez un ou plusieurs événements auxquels vous souhaitez vous abonner.

Événement	Description
run_completed	Un run d'anonymisation s'est terminé avec succès.
run_failed	Un run d'anonymisation a échoué (erreur de connexion, règle invalide, etc.).
run_cancelled	Un run a été annulé manuellement ou automatiquement avant la fin.

Format du payload

Les webhooks sont délivrés en POST avec un Content-Type application/json. Le corps de la requête respecte toujours la structure suivante :

application/json

{
  "event": "run_completed",
  "run_id": "5f9c2c84-2a3a-4b2b-9b6a-2f7f0a4b9c1d",
  "project_id": "1a2b3c4d-5e6f-7890-abcd-ef0123456789",
  "timestamp": "2026-05-23T12:00:00.000Z",
  "data": {
    "status": "succeeded",
    "rows_processed": 124530,
    "duration_ms": 18742
  }
}

Sécurité et vérification de la signature

Chaque webhook possède un secret unique fourni à la création. Anonyx l'utilise pour calculer un HMAC-SHA256 sur le corps brut du POST, transmis dans l'en-tête HTTP. Vérifiez systématiquement cette signature côté serveur avant de traiter l'événement.

X-Anonyx-Signature — signature HMAC-SHA256 au format sha256=<hex>, calculée sur le corps JSON brut.
X-Anonyx-Event — type d'événement délivré (run_completed, run_failed ou run_cancelled).
X-Anonyx-Delivery-Id — identifiant unique de la livraison, utile pour l'idempotence et la corrélation des logs.

Les URL cibles doivent obligatoirement utiliser HTTPS. Les URL en clair sont rejetées à la création.

Exemples de vérification

import crypto from 'node:crypto';

export function verifyAnonyxSignature(
  rawBody: string,
  headerValue: string,
  secret: string,
): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(headerValue),
  );
}

Retries et timeouts

Anonyx considère la livraison comme réussie dès qu'il reçoit une réponse 2xx en moins de 10 secondes. Sinon, la requête est ré-essayée selon une politique de backoff exponentiel.

Jusqu'à 5 tentatives par événement.
Backoff exponentiel : 5 s, 25 s, 125 s, 625 s, puis 3 125 s entre chaque tentative.
Toute réponse HTTP 2xx marque la livraison comme réussie.
Le timeout est fixé à 10 secondes par tentative.

Bonnes pratiques

Utilisez X-Anonyx-Delivery-Id comme clé d'idempotence : le même événement peut être livré plusieurs fois en cas de retry.
Répondez en moins de 10 secondes, sinon la requête sera traitée comme un échec et ré-essayée.
Si votre traitement est long, accusez réception (200) puis traitez le payload dans une file asynchrone.
Stockez le secret du webhook côté serveur uniquement et faites-le tourner régulièrement via l'API ou l'interface.