Configurer un endpoint webhook

Prérequis : l’option Webhooks sur votre compte, activée par Beedeez. Sans elle, la page n’apparaît pas dans le menu.

Droits nécessaires : le droit Modifier la personnalisation, sur le compte parent. L’entrée est également inaccessible lorsqu’un département est sélectionné : repassez sur le compte parent.

Un webhook fait appeler par Beedeez une URL de votre côté quand un événement se produit. Cette page décrit la configuration d’un point de terminaison et le contrat de livraison. Le formulaire propose plus d’événements qu’il n’en part réellement : lisez d’abord Les événements webhook disponibles.

Ajouter un point de terminaison

1. Ouvrez le menu Configuration, puis la section Intégration et la page Webhooks. Un bandeau rappelle qu’il s’agit d’une section technique avancée.
2. Dans la section Points de terminaison Webhook, cliquez sur Ajouter un point de terminaison. La fenêtre de création s’ouvre.
3. Renseignez les champs décrits ci-dessous. Au moins un événement est obligatoire.
4. Validez la fenêtre. Le point de terminaison apparaît dans la liste, mais la configuration n’est pas encore enregistrée.
5. Cliquez sur Tout sauvegarder, en bas du panneau de gauche. La configuration est écrite à ce moment précis.

Pour reprendre un point de terminaison existant, ouvrez Modifier le point de terminaison, puis terminez de la même manière par Tout sauvegarder.

Les champs du formulaire

Le formulaire est affiché en anglais, quelle que soit la langue de l’interface.

• Name : votre libellé. Il sert à vous repérer dans la liste et n’a aucun effet sur l’envoi.
• URL : l’adresse appelée. Aucune validation n’est appliquée : le HTTPS n’est pas exigé, le format n’est pas contrôlé et l’adresse n’est jamais testée à l’enregistrement. Une URL fautive s’enregistre sans avertissement.
• Timeout (ms) : ce champ s’enregistre mais n’est pas appliqué. Le délai d’attente de votre réponse est de 5 secondes, dans tous les cas.
• Event Types : les événements auxquels ce point de terminaison est abonné, présentés sous forme d’étiquettes cliquables.
• Authentication : le champ Type propose None, Bearer Token, Basic Auth, API Key et Custom Header. Selon le choix, vous renseignez Token, Username et Password, ou Header Name et Header Value. API Key envoie le jeton dans l’en-tête X-API-Key ; Custom Header n’accepte qu’un seul couple nom et valeur.

Ce que Beedeez envoie

Beedeez émet une requête POST en Content-Type: application/json. Les seuls en-têtes transmis sont ce Content-Type, celui du mode d’authentification retenu et votre en-tête personnalisé s’il y en a un. Une réponse 2xx vaut accusé de réception ; tout autre code, comme l’absence de réponse dans les 5 secondes, compte comme un échec.

⚠️ Le corps ne contient pas d’enveloppe d’événement. Vous recevez l’objet métier concerné, sans nom d’événement, sans horodatage d’envoi ni identifiant de livraison. Pour distinguer deux événements, déclarez un point de terminaison par événement et faites porter la distinction par l’URL.

Aucune signature n’est transmise

Aucune signature n’est calculée ni envoyée : il n’existe ni champ secret dans le formulaire, ni en-tête de signature dans la requête. Si votre projet attend un en-tête X-Hub-Signature-256, il attend quelque chose qui n’arrivera pas.

💡 Conseil : traitez l’URL comme un secret et renseignez toujours un mode d’authentification. C’est la seule preuve d’origine dont vous disposez, car quiconque connaît l’adresse peut vous envoyer un faux événement.

Les limites de la livraison

• Aucune nouvelle tentative. Un échec n’est pas rejoué. L’événement est journalisé côté Beedeez, puis abandonné. Si vous ne pouvez pas vous permettre de le perdre, prévoyez une réconciliation périodique par l’API ou par export.
• Aucun historique de livraison et aucun bouton de test. Les compteurs de succès et d’échec affichés sur chaque point de terminaison ne sont jamais alimentés et restent à zéro. Le seul contrôle possible consiste à déclencher un événement réel, puis à observer ce qui arrive chez vous.
• Aucun ordre garanti. Plusieurs envois partent en parallèle : deux événements peuvent vous parvenir dans le désordre.
• Aucune unicité garantie. Un envoi peut être rejoué en interne. Rendez votre traitement idempotent : recevoir deux fois le même événement doit produire le même résultat qu’une seule réception.
• Aucune restriction par adresse IP.

Deux pièges à connaître

Ajouter ou modifier un point de terminaison ne l’enregistre pas. La fenêtre met à jour l’écran ; la configuration n’est écrite qu’au clic sur Tout sauvegarder, en bas du panneau de gauche. Quitter la page avant cette étape perd la saisie.

Le commutateur global n’arrête pas les envois. Le commutateur Activer les webhooks des Paramètres globaux n’interrompt pas les appels : c’est celui de chaque point de terminaison qui est lu au moment de l’envoi. Pour arrêter les envois, désactivez ou supprimez les points de terminaison un par un, puis enregistrez.

Pour aller plus loin

• Les événements webhook disponibles : la liste réellement émise, à lire avant tout développement.
• API publique, webhooks, callbacks : que choisir : les cas où un webhook n’est pas le bon mécanisme.
• Générer et gérer vos clés d’API : le chemin de réconciliation quand un événement a été perdu.
• Validité, expiration et renouvellement : ce qui déclenche les événements aujourd’hui disponibles.