Référence des Webhooks

Les webhooks envoient des requêtes HTTP POST à votre endpoint lorsque des événements se produisent dans Umbrella : vous n’avez donc pas besoin d’interroger l’API pour détecter les changements.

Configuration

1. Accédez à Tableau de bord > Paramètres > Intégrations > Webhooks
2. Cliquez sur Ajouter un endpoint de webhook
3. Saisissez l’URL HTTPS de votre endpoint
4. Sélectionnez les événements que vous souhaitez recevoir
5. Enregistrez, puis conservez le secret de signature (il n’est affiché qu’une seule fois)

Votre endpoint doit accepter les requêtes POST, renvoyer un statut 2xx en moins de 30 secondes et accepter application/json.

Types d’événements

Événements de police

Événements de réclamation

Événements d’enregistrement

Événements de garantie

Structure de la charge utile

Chaque webhook suit cette enveloppe :

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "claim.submitted",
  "timestamp": "2025-03-15T14:30:00.000Z",
  "apiVersion": "1.3.9",
  "orgId": "org_xyz789",
  "data": { ... }
}

• id — identifiant unique de l’événement (à utiliser pour la déduplication)
• type — type d’événement
• timestamp — moment où l’événement s’est produit
• data — charge utile propre à l’événement, contenant les détails de la ressource concernée (police, réclamation, enregistrement, etc.)

Vérification de la signature

Chaque requête comporte un en-tête X-Umbrella-Signature contenant un hachage HMAC-SHA256 du corps de la requête. Vérifiez-le avant de traiter les événements.

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Stratégie de nouvelles tentatives

Les livraisons en échec (statut autre que 2xx, délai dépassé, erreur de connexion) sont relancées avec un délai exponentiel :

Après 7 tentatives infructueuses, la livraison est marquée comme échouée. Une réponse 410 Gone désactive définitivement l’endpoint.

Tests

1. Accédez à Tableau de bord > Paramètres > Intégrations > Webhooks
2. Cliquez sur votre endpoint, puis sur Envoyer un événement de test
3. Sélectionnez un type d’événement et consultez le résultat de la livraison

La page de détail du webhook affiche également un journal des livraisons récentes, avec les codes de statut et les temps de réponse.

Voir aussi

• Authentification — Sécurité et identifiants de l’API
• API des réclamations — Endpoints de gestion des réclamations
• API des polices — Endpoints de gestion des polices