Webhooks

Pourquoi utiliser les webhooks

Vous pouvez recevoir des événements pour être notifié des mises à jour de votre intégration en temps réel. Payment Gateway utilise les webhooks à cette fin. Un webhook est un code qui envoie un objet événement vers un endpoint lorsqu'un objet API v.2 est modifié.

Pour activer les événements webhook, vous devez enregistrer des endpoints 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

Consultez 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 aboutir à la création de plusieurs événements. Par exemple, si vous complétez un paiement en deux étapes (effectuer une capture), vous recevez les événements payment.funded et payment.succeeded.

Structure de l'en-tête d'événement

Chaque requête possède 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 d'événement

Le corps d'événement contient les attributs suivants.

Exemple du corps d'é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 endpoint webhook en suivant les étapes ci-dessous. Vous pouvez enregistrer et créer un endpoint ou plusieurs endpoints.

1. Identifier les événements à surveiller

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

2. Créer une fonction endpoint webhook

Configurez une fonction endpoint HTTPS qui peut accepter les requêtes webhook avec une méthode POST. Configurez votre fonction endpoint pour qu'elle :

• Gère les requêtes POST avec une charge utile JSON constituée d'un objet événement.
• Retourne rapidement un code de statut de réussite (2xx) avant toute logique complexe qui pourrait provoquer un délai d'expiration. Par exemple, vous devez retourner une réponse 200 avant de mettre à jour la facture d'un client comme payée dans votre système comptable.

3. Enregistrer votre endpoint webhook via l'Espace Personnel

Vous pouvez configurer votre intégration webhook via votre Espace personnel. Pour ce faire :

1. Connectez-vous à l'Espace personnel.
2. Allez dans Paramètres > Webhooks.
3. Sélectionnez Webhooks activés.

Les champs pour configurer les webhooks apparaîtront :

Configurez les champs suivants :

• URL de l'endpoint - saisissez l'URL de l'endpoint webhook. Le format d'URL pour enregistrer un endpoint webhook est : https://<your-website>/<your-webhook-endpoint>. Par exemple : https://mybestmerchantreturnurl.com/webhooks. Pour ajouter plus d'endpoints, cliquez sur le bouton Ajouter un endpoint.
• Secret de signature – saisissez le secret pour vérifier que les événements proviennent de la passerelle de paiement. Vous pouvez cliquer sur Générer pour générer le secret automatiquement. Le secret généré sera affiché dans ce champ.
• Sélectionner les événements à écouter – sélectionnez les événements qui seront envoyés aux endpoints spécifiés. Sélectionnez l'objet (par exemple, Session), développez la section puis sélectionnez les événements correspondants.

Cliquez ensuite sur Enregistrer pour enregistrer votre/vos endpoint(s) pour recevoir les événements sélectionnés.

Quand un webhook échoue

Si une réponse autre que 200 OK est retournée à la Passerelle de Paiement, l'envoi de l'é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 à intervalles de 30 secondes jusqu'à ce qu'une des conditions suivantes soit remplie :

• la Passerelle de Paiement reçoit 200 OK, OU
• il y a 3 échecs successifs de webhook.

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

N'écouter que les types d'événements requis par votre intégration

Configurez vos endpoints webhook pour recevoir uniquement 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, nous ne le recommandons donc pas. Vous pouvez modifier les événements qu'un endpoint webhook reçoit via l'Espace personnel.

Recevoir les événements avec un serveur HTTPS

Si vous utilisez une URL HTTPS pour votre endpoint webhook, la Passerelle de Paiement valide que la connexion à votre serveur est sécurisée avant d'envoyer vos données webhook. Pour que cela fonctionne, votre serveur doit être correctement configuré pour supporter HTTPS avec un certificat 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. Divisez ensuite 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 aux signatures).

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

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

• L'horodatage (comme 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 de l'endpoint 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 les signatures) dans l'en-tête avec 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 temporisation, utilisez une comparaison de chaîne à temps constant pour comparer la signature attendue à chacune des signatures reçues.

Utilisez le support de deux signing secrets

De nombreuses entreprises exigent de changer le signing secret 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 changer votre signing secret, générez d'abord le nouveau signing secret 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. Supportez deux secrets : 1) l'ancien, 2) le nouveau que vous avez généré.
3. Changez l'ancien secret vers le nouveau secret via l'Espace Personnel (saisissez-le dans le champ Signing secret et cliquez sur Save).
4. Assurez-vous que les événements reçus sont correctement vérifiés par le nouveau secret. Si quelque chose ne va pas, changez le secret de retour vers l'ancien.
5. Si tout fonctionne correctement, supprimez l'ancien secret de vos systèmes.