Webhooks & API

Configurer un webhook

Dans l'application : Paramètres → Webhooks → Ajouter. Indiquez l'URL HTTPS de votre endpoint et sélectionnez les événements à recevoir. Un secret de signature est généré : conservez-le, il sert à vérifier l'authenticité de chaque notification.

Format des notifications

Chaque événement est envoyé en POST sur votre URL, corps JSON, en-tête Content-Type: application/json. Les montants sont toujours exprimés en centimes d'euro (entiers).

{
  "event": "payslip.calculated",
  "timestamp": "2026-06-15T09:30:00+02:00",
  "data": {
    "payslipId": "0f47ac10-58cc-4372-a567-0e02b2c3d479",
    "employeeId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "period": "2026-06",
    "grossInCents": 285000,
    "netPayableInCents": 222347
  }
}

Vérifier la signature

Chaque requête porte l'en-tête X-Ebulletin-Sig: sha256=<hmac>, calculé en HMAC-SHA256 du corps brut avec votre secret. Rejetez toute requête dont la signature ne correspond pas — utilisez une comparaison à temps constant.

// Node.js — vérification de la signature
import crypto from "node:crypto";

function verifyWebhook(rawBody, signatureHeader, secret) {
  // signatureHeader = "sha256=<hmac hexadécimal>"
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected),
  );
}

Bonnes pratiques

• Répondez 2xx en moins de 10 secondes — traitez le contenu de façon asynchrone si nécessaire.
• En cas d'échec (timeout ou statut non-2xx), la notification est retentée avec backoff exponentiel.
• Traitez les notifications de façon idempotente : une même notification peut, rarement, être livrée deux fois.
• Le secret peut être régénéré à tout moment depuis Paramètres → Webhooks (l'ancien est invalidé immédiatement).