Webhooks

Un webhook, dans le développement web, est une méthode permettant d'augmenter ou de modifier le comportement d'une page web ou d'une application web à l'aide de rappels (callbacks) personnalisés. Ces rappels peuvent être maintenus, modifiés et gérés par des utilisateurs et développeurs tiers qui ne sont pas nécessairement affiliés au site web ou à l'application d'origine.

Besoin de plus de détails ?
Retrouvez plus d'informations techniques sur nos webhooks et sur leur contenu dans notre documentation technique.

Accéder à l'interface des webhooks

Dans le menu de navigation à gauche, cliquez sur Configurations → Intégrations et outils → Webhooks.

Configuration du webhook

Cliquez sur Configuration dans le coin supérieur droit.
Dans Webhook urls, ajoutez une URL et cliquez sur Add.
Sélectionnez un ou plusieurs types d'événements
Ajoutez une adresse e-mail dans le champ Alert emails et cliquez sur Add.
Saisissez un nom d'utilisateur et un mot de passe dans le champ Credentials.
Vous pouvez copier la clé Secret en cliquant sur .
Activez le webhook à l'aide de l'interrupteur Status .
Cliquez sur Save.

Explication des webhooks en attente

Il arrive que des webhooks restent en attente et semblent même ne pas être envoyés à votre serveur.

Premier entré, premier sorti

Tous les webhooks sont envoyés selon un ordre FIFO (first in, first out - premier entré, premier sorti), regroupés par client.

Cela signifie que vous pouvez vous attendre à recevoir les événements de chaque client dans le bon ordre.

Exemple : vous ne recevrez pas CUSTOMER_UPDATED avant CUSTOMER_CREATED.

Remarque
Si votre service ne renvoie pas un code HTTP compris entre 200 et 299 :
nous considérons le webhook comme ayant échoué
nous bloquerons les webhooks suivants pour ce client spécifique

Points à prendre en compte pour les webhooks

Votre point de terminaison doit répondre dans un délai de 30 secondes.
Une réponse avec un code HTTP 2XX est considérée comme réussie. Toutes les autres réponses sont considérées comme des échecs.
Le contenu d'un webhook notifie un événement survenu dans le système Frisbii Payment, les ressources concernées et le type d'événement, mais ne contient en lui-même aucun état. Il est recommandé d'utiliser ensuite l'API pour obtenir l'état actualisé d'une ressource.
Votre point de terminaison doit être idempotent, ce qui permet à plusieurs appels d'un même webhook de produire le même résultat qu'un seul appel.
Cela s'explique par le fait que des erreurs de communication peuvent conduire à une situation où Frisbii Payments considère un appel comme ayant échoué alors qu'il a bien été reçu. Nous relancerons les appels ayant échoué. Voir ci-dessous.
Dans les scénarios d'échec, les webhooks peuvent être livrés dans le désordre. Par conséquent, utilisez toujours l'API pour obtenir l'état réel d'une ressource.
Un exemple est l'annulation d'un abonnement suivie d'une réactivation. Le webhook d'annulation pourrait être reçu après celui de réactivation.

Bonne pratique

Frisbii Payment enverra au maximum 10 requêtes webhook à votre serveur à la fois.

Une bonne pratique consiste à transférer les événements vers une file d'attente locale de votre côté et à renvoyer 200 OK pour chacun.

Cela signifie que vous répondrez rapidement et qu'aucun événement ne bloquera les autres. Vous pouvez ensuite traiter chaque événement de votre file d'attente et mettre à jour vos ressources sans problème.

Exemples de webhooks et de leur contenu

INVOICE_CREATED

{
"id":"cd614e4887c8c12ae67fbf80c3ffc1b6",
"timestamp":"2025-11-11T13:19:18.99Z",
"signature":"7718c7690b51f2c9b1cee2a173b6eb81aab2b4849e8eb8544c3a3ee2640231e1",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"invoice_created",
"event_id":"f131c9306108777bab8e1e0278e76480"
}

INVOICE_REFUND

{
"id":"b6cfe85ab18d65d2750f093a6e59400c",
"timestamp":"2025-11-11T13:33:04.803Z",
"signature":"9674d2ff0482157d149ade9d071243df448f891e36c42dcb2fba6eaa887b7401",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"transaction":"5ccb1455b072adf948c0e93d4a26e103",
"event_type":"invoice_refund",
"event_id":"e1d018b2fb86f62464ea219f81636598",
"credit_note":"5ccb1455b072adf948c0e93d4a26e103"
}

SUBSCRIPTION_RENEWAL

{
"id":"abefe07e4a742cce106695dd8238bdcb",
"timestamp":"2025-11-11T13:19:18.99Z",
"signature":"12b4423aaf65ce0978fb0ba752d147618051fc1a9ac0f9c50377a456922848e7",
"invoice":"inv-52",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"subscription_renewal",
"event_id":"20127731fe4a68ef674c4d4cffcda2af"
}

SUBSCRIPTION_EXPIRED

{
"id":"2585ec2c89395a515c8f47afa2920899",
"timestamp":"2025-11-11T13:33:04.738Z",
"signature":"99fcf1acddd18bad4615fd95a52934a28bc589cb5682efbe28a34fb7baf460fd",
"subscription":"sub-0022",
"customer":"cust-0005",
"event_type":"subscription_expired",
"event_id":"8ae7b7b17a5b1612ea38e9f714c9259f"
}

CUSTOMER_PAYMENT_METHOD_ADDED

{
"id":"e1c69ad60688cfb4cf38ca6a6c75959a",
"timestamp":"2025-11-11T13:28:14.601Z",
"signature":"3106e26798b59a20b3b0f8135ec6fe4205c7b5e8fb62498b6d19bea82317e64c",
"customer":"cust-0005",
"event_type":"customer_payment_method_added",
"event_id":"3e17853629d60230e1178e436087b699",
"payment_method":"ca_dc1a6deb3b702b6564531ec21d1da6cf",
"payment_method_reference":"cs_4c5ad0ac03ddd97efa33d7b48ef18b9a"
}