Vue d'ensemble des webhooks

Vue d'ensemble des webhooks

Les webhooks permettent à votre application de recevoir des notifications HTTP POST en temps réel lorsque des événements se produisent dans votre organisation ZenFlip. Au lieu d'interroger l'API pour détecter les changements, vous enregistrez une URL et ZenFlip y envoie automatiquement les charges utiles des événements.

Événements disponibles

ZenFlip envoie des webhooks pour les types d'événements suivants :

Enregistrer un webhook

Configurez les URL de webhook dans le tableau de bord ZenFlip :

1. Naviguez vers Paramètres > Webhooks.

2. Cliquez sur Ajouter un endpoint webhook.

3. Saisissez l'URL où vous souhaitez recevoir les événements (doit être HTTPS).

4. Sélectionnez les événements auxquels vous souhaitez vous abonner (ou sélectionnez tous).

5. Cliquez sur Enregistrer.

ZenFlip génère un secret de signature pour chaque endpoint webhook. Copiez-le et stockez-le de manière sécurisée --- vous en aurez besoin pour vérifier les signatures des webhooks.

Vous pouvez enregistrer plusieurs endpoints webhook. Chaque endpoint peut s'abonner à différents types d'événements.

Format de la charge utile

Chaque livraison de webhook est une requête HTTP POST avec un corps JSON. La structure de la charge utile est cohérente pour tous les types d'événements :

`json { "id": "wh_del_550e8400-e29b-41d4-a716-446655440000", "event": "publication.converted", "createdAt": "2026-02-20T14:05:00.000Z", "organizationId": "660e8400-e29b-41d4-a716-446655440000", "data": { "publicationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "title": "Product Catalog 2026", "versionNumber": 2, "status": "ready", "pageCount": 24 } } `

Champs de niveau supérieur

En-têtes de requête

Chaque requête webhook inclut les en-têtes personnalisés suivants :

Vérification de signature

Chaque requête webhook est signée avec le secret de signature de votre endpoint en utilisant HMAC-SHA256. Vérifiez toujours la signature pour confirmer que la requête provient de ZenFlip et n'a pas été altérée.

La signature est calculée sur le corps brut de la requête :

` HMAC-SHA256(signing_secret, raw_request_body) `

Le résultat est envoyé sous forme de chaîne hexadécimale dans l'en-tête X-ZenFlip-Signature.

Exemple de vérification (Node.js)

`javascript const crypto = require("crypto");

function verifyWebhookSignature(rawBody, signature, secret) { const expected = crypto .createHmac("sha256", secret) .update(rawBody, "utf8") .digest("hex");

// Utiliser une comparaison sécurisée pour prévenir les attaques temporelles return crypto.timingSafeEqual( Buffer.from(signature, "hex"), Buffer.from(expected, "hex") ); }

// Dans votre gestionnaire de route Express app.post("/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { const signature = req.headers["x-zenflip-signature"]; const secret = process.env.ZENFLIP_WEBHOOK_SECRET;

if (!verifyWebhookSignature(req.body, signature, secret)) { console.error("Invalid webhook signature"); return res.status(401).send("Invalid signature"); }

const event = JSON.parse(req.body); console.log("Received event:", event.event, event.id);

// Traiter l'événement...

res.status(200).send("OK"); }); `

Important : Utilisez express.raw() (ou équivalent) pour accéder au corps brut de la requête pour la vérification de signature. Analyser le corps en JSON puis le reconvertir en chaîne peut produire une séquence d'octets différente qui ne correspondra pas à la signature.

Politique de reprise

Si votre endpoint ne répond pas avec un code de statut 2xx dans les 10 secondes, ZenFlip considère la livraison comme échouée et réessaie avec un backoff exponentiel :

Après 4 tentatives au total (1 initiale + 3 reprises), la livraison est marquée comme failed. Vous pouvez consulter l'historique des livraisons et relancer manuellement les échecs depuis le tableau de bord.

Idempotence

Chaque livraison possède un id unique (également envoyé dans l'en-tête X-ZenFlip-Delivery-Id). Utilisez cet identifiant pour dédupliquer les événements au cas où la même livraison serait reçue plus d'une fois en raison de reprises ou de problèmes réseau.

Exigences de réponse

Votre endpoint webhook doit :

1. Répondre avec un HTTP 2xx (200, 201, 202, 204) pour accuser réception.

2. Répondre dans les 10 secondes. Si vous devez effectuer un traitement long, accusez réception du webhook immédiatement et traitez de manière asynchrone.

3. Accepter les requêtes POST avec Content-Type: application/json.

`javascript // Modèle recommandé : accuser réception immédiatement, traiter de manière asynchrone app.post("/webhooks/zenflip", express.raw({ type: "application/json" }), (req, res) => { // Vérifier la signature d'abord // ...

// Accuser réception immédiatement res.status(200).send("OK");

// Traiter de manière asynchrone const event = JSON.parse(req.body); processWebhookEvent(event).catch(console.error); }); `

Tester les webhooks

Le tableau de bord ZenFlip inclut un outil de test de webhooks :

1. Allez dans Paramètres > Webhooks.

2. Cliquez sur le bouton Tester à côté de votre endpoint.

3. Sélectionnez un type d'événement pour envoyer un exemple de charge utile.

4. Consultez le journal de livraison pour voir la requête, la réponse et les éventuelles erreurs.

Vous pouvez également utiliser des outils comme ngrok pour exposer un serveur de développement local sur Internet à des fins de test :

`bash

Démarrer ngrok pour créer une URL publique pour votre serveur local

ngrok http 3000

Utilisez l'URL générée (ex. : https://abc123.ngrok.io/webhooks/zenflip)

comme endpoint webhook dans le tableau de bord ZenFlip

`

Historique des livraisons

Toutes les livraisons de webhooks sont enregistrées et accessibles depuis le tableau de bord. Chaque entrée affiche :

• Le type d'événement et l'identifiant de livraison

• L'horodatage

• Le code de statut HTTP de la réponse de votre endpoint

• Le corps de la réponse (1 000 premiers caractères)

• Le nombre de tentatives

• Le statut actuel : pending, success ou failed

Prochaines étapes

• [Référence des événements webhook](/docs/webhooks-events) --- Schémas de charge utile détaillés pour chaque type d'événement avec des exemples JSON.