Webhooks

Pourquoi utiliser les webhooks

Vous pouvez recevoir des événements pour être informé des mises à jour de votre intégration en temps réel. La passerelle de paiement utilise des webhooks à cette fin. Un webhook est un code qui envoie un objet événement à un point de terminaison lorsqu'un objet API v.2 est modifié.

Pour activer les événements webhook, vous devez enregistrer les points de terminaison webhook, générer un secret pour signer les événements et sélectionner les événements à écouter. Vous pouvez configurer ces paramètres via l'Espace personnel.

Actuellement, vous pouvez recevoir les événements liés aux objets suivants :

• Session
• Payment
• PaymentMethod
• Refund

Voir la liste complète des types d'événements pris en charge.

Aperçu des événements

Chaque événement est une requête POST avec un corps JSON, avec une signature symétrique avec HMAC.

Une seule requête API peut entraîner la création de plusieurs événements. Par exemple, si la tentative de paiement pour une Session, créée dans le cadre de l'[intégration par redirection]((/integration/apiv2/structure/redirect-integration-apiv2.html), échoue et qu'il ne reste plus de tentatives de paiement, vous recevez les événements session.completed, payment.failed et payment.canceled.

Structure de l'en-tête des événements

Chaque requête a les en-têtes suivants :

• X-Version - version de l'API au format YYYY-MM-DD (exemple : 2023-11-15) ;
• X-Signature – signature pour webhook ;
• API-Request-Id – identifiant de requête (format : req_UUID).

Exemple :

-H "Content-Type: application/json" \
-H "X-Signature: your_webhook_signature" \
-H "X-Version: 2023-11-15" \

Structure du corps des événements

Le corps de l'événement contient les attributs suivants :

Exemple du corps de l'événement :

{
  "created": "2022-02-17T16:30:55+00:00",
  "data": {
    "object": {
      "id": "ps_2njmpfC9BUCfsmALYNEQv5eoR8SdVsEHuXZC7D3uLiRxqfb8g2wJzWo8UvE9QL",
      "amount": 90000,
      "created": "2022-02-17T16:10:54+00:00",
      "currency": "EUR",
      "expiresAt": "2022-02-17T16:10:54+00:00",
      "failureUrl": "https://mybestmerchantreturnurl.com/failure",
      "locale": "en",
      "paymentData": {
        "captureMethod": "automatic"
      },
      "paymentStatus": "unpaid",
      "paymentUrl": "https://dev.bpcbt.com/payment/merchants/ecom/payment.html?mdOrder=0fbfe391-c2d1-7528-a0a9-5a4500a99ded&language=en",
      "status": "expired",
      "successUrl": "https://mybestmerchantreturnurl.com/success"
    }
  },
  "type": "session.expired"
}

Types d'événements

Les types d'événements suivants sont pris en charge.

Version de l'API

La version de l'API sera spécifiée dans l'en-tête X-Version de l'événement.

Pourquoi les objets événement sont-ils générés

Les scénarios suivants peuvent déclencher la génération d'objets événement :

• Lorsque vous effectuez des modifications via l'Espace personnel (par exemple, effectuer un remboursement)
• Lorsque vous utilisez l'API
• Lorsqu'un client fait quelque chose via la page de paiement

Comment configurer votre intégration webhook

Pour commencer à recevoir des événements webhook, créez et enregistrez un point de terminaison webhook en suivant les étapes ci-dessous. Vous pouvez enregistrer et créer un point de terminaison ou plusieurs points de terminaison.

1. Identifier les événements à surveiller

Utilisez le tableau Types d'événements pour identifier les événements que vous souhaitez recevoir.

2. Créer une fonction de point de terminaison webhook

Configurez une fonction de point de terminaison HTTPS qui peut accepter les demandes de webhook avec une méthode POST. Configurez votre fonction de point de terminaison de sorte qu'elle :

• Traite les demandes POST avec une charge utile JSON composée d'un objet d'événement.
• Renvoie rapidement un code de statut de réussite (2xx) avant toute logique complexe qui pourrait causer un timeout. Par exemple, vous devez renvoyer une réponse 200 avant de mettre à jour la facture d'un client comme payée dans votre système comptable.

3. Enregistrer votre point de terminaison webhook via l'Espace Personnel

Vous pouvez configurer votre intégration webhook via votre Espace personnel. Voir les détails dans le Guide Utilisateur du Portail Marchand.

Quand un webhook échoue

Si une réponse autre que 200 OK est retournée à la passerelle de paiement, l'envoi d'événement est considéré comme non réussi. Dans ce cas, la passerelle de paiement répète l'envoi de l'événement à des intervalles de 30 secondes jusqu'à ce qu'une des conditions suivantes soit remplie :

• la passerelle de paiement reçoit 200 OK,
• il y a 3 échecs de webhook successifs.

Quand une des conditions ci-dessus est remplie, les tentatives d'envoi d'un événement s'arrêtent.

Meilleures pratiques pour utiliser les webhooks

Écouter seulement les types d'événements que votre intégration nécessite

Configurez vos points de terminaison webhook pour recevoir seulement les types d'événements requis par votre intégration. Écouter des événements supplémentaires (ou tous les événements) crée une charge excessive sur votre serveur, donc nous ne le recommandons pas. Vous pouvez changer les événements qu'un point de terminaison webhook reçoit via l'Espace personnel.

Recevoir les événements avec un serveur HTTPS

Si vous utilisez une URL HTTPS pour votre point de terminaison webhook, la passerelle de paiement valide que la connexion à votre serveur est sécurisée avant d'envoyer vos données de webhook. Pour que cela fonctionne, votre serveur doit être correctement configuré pour supporter HTTPS avec un certificat de serveur valide.

Vérifier que les événements sont envoyés depuis la passerelle de paiement

L'en-tête X-Signature inclus dans chaque événement signé contient un horodatage et une ou plusieurs signatures que vous devez vérifier. L'horodatage est préfixé par t=, et chaque signature est préfixée par v1=. La passerelle de paiement génère les signatures en utilisant HMAC avec SHA-256.

Exemple de l'en-tête X-Signature :

X-Signature: t=1492774577,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

Pour vérifier la signature, suivez ces étapes :

Étape 1 : Extraire l'horodatage et les signatures de l'en-tête

Divisez l'en-tête en utilisant le caractère , comme séparateur pour obtenir une liste d'éléments. Puis divisez chaque élément en utilisant le caractère = comme séparateur pour obtenir une paire préfixe et valeur. La valeur pour le préfixe t correspond à l'horodatage, et v1 correspond à la signature (ou signatures).

Étape 2 : Préparer la chaîne signed_payload

La chaîne signed_payload est créée en concaténant :

• L'horodatage (comme une chaîne)
• Le caractère .
• La charge utile JSON réelle (c'est-à-dire, le corps de l'événement)

Étape 3 : Déterminer la signature attendue

Calculez un HMAC avec la fonction de hachage SHA256. Utilisez le secret de signature du point de terminaison comme clé et utilisez la chaîne signed_payload comme message. La valeur résultante sera la signature attendue.

Étape 4 : Comparer les signatures

Comparez la signature (ou signatures) dans l'en-tête à la signature attendue. Pour une correspondance d'égalité, calculez la différence entre l'horodatage actuel et l'horodatage reçu, puis décidez si la différence est dans votre tolérance. Pour protéger contre les attaques de timing, utilisez une comparaison de chaîne à temps constant pour comparer la signature attendue à chacune des signatures reçues.

Utiliser le support de deux secrets de signature

Beaucoup d'entreprises exigent de changer le secret de signature de temps en temps à des fins de sécurité. Pour effectuer ce changement en toute sécurité, nous vous recommandons d'utiliser l'approche suivante :

1. Lorsque vous allez modifier votre secret de signature, générez d'abord un nouveau secret de signature manuellement ou en utilisant l'outil de votre choix (le secret doit être une chaîne aléatoire avec au moins 20 symboles - chiffres et caractères latins).
2. Prenez en charge deux secrets : 1) l'ancien, 2) le nouveau que vous avez généré.
3. Changez l'ancien secret pour le nouveau secret via l'Espace Personnel (saisissez-le dans le champ Secret de signature et cliquez sur Enregistrer).
4. Assurez-vous que les événements reçus sont correctement vérifiés par le nouveau secret. Si quelque chose ne va pas, remettez le secret à l'ancien.
5. Si tout fonctionne correctement, supprimez l'ancien secret de vos systèmes.