Webhooks > Introduction

Utilisez les webhooks lorsque votre système doit être informé des paiements et des messages dès qu'ils surviennent, plutôt que d'interroger Hyfin sans cesse.

Les webhooks permettent à Hyfin d'informer votre système des changements en temps réel, sans que vous ayez à vérifier constamment. Une fois activés, Hyfin envoie un message à votre URL dès qu'un événement se produit.

Activation des webhooks

Vous activez les webhooks pour un site entier ou pour une facture en envoyant une URL de webhook au point de terminaison correspondant. Voici le JSON dont chaque point de terminaison a besoin.


Point de terminaison
Échantillon JSON
Ajouter/Mettre à jour le site
Lorsque vous ajoutez ou mettez à jour un site, vous pouvez activer un webhook pour l'ensemble du site. Un webhook de site vous envoie toutes les notifications de facture et de paiement pour ce site.
			
{
  "externalId": "12345678",
  "webhook": {
    "active": true,
    "url": "https://mysoftware.com/webhook"
  }
}


		
Ajouter/Mettre à jour la facture
Lorsque vous ajoutez ou mettez à jour une facture, vous pouvez activer un webhook pour cette facture. Il vous envoie toutes les notifications concernant la facture.
			
{
  "_id": "39772921",
  "webhookUrl": "https://mysoftware.com/webhook/{invoice_id}"
}


		

Événements de webhook

Lorsqu'une URL de webhook est définie, Hyfin envoie les messages suivants.

Action
Détail
Paiement
Un paiement sur une facture atteint un nouveau statut, par exemple capturé, réglé, annulé, remboursé ou faisant l'objet d'une rétrofacturation. Chaque statut est envoyé une seule fois par paiement.
Notification
Un message texte, un courriel ou un message WhatsApp a été envoyé, livré, lu, retardé ou a échoué, ou le client a cliqué sur le lien de paiement.

Tentatives

L'URL de votre webhook doit répondre avec un code d'état HTTP de réussite (tout code 2xx) en moins de 30 secondes. Un état autre que 2xx, un délai d'attente dépassé ou une connexion impossible à établir est considéré comme un échec de livraison, et le message est renvoyé selon le calendrier suivant.

Tentative de réessai
Renvoyé
#1
5 minutes après le webhook initial
#2
1 heure plus tard
#3
2 heures plus tard
#4
24 heures plus tard
#5
48 heures plus tard

Il y a au plus cinq tentatives de nouvel envoi. Chaque délai du tableau est mesuré à partir de la tentative précédente plutôt qu'à partir du webhook initial; la cinquième et dernière tentative a donc lieu environ 3,1 jours après celui-ci. Si cette tentative échoue aussi, le message n'est plus renvoyé.

Règles de livraison

  • L'URL du webhook doit utiliser HTTPS. Aucune livraison n'est effectuée vers une URL qui utilise HTTP, et aucune nouvelle tentative n'a lieu.
  • Une URL qui pointe vers une adresse réseau privée, de bouclage ou réservée est refusée. Une requête qui en définit une est rejetée, et aucune livraison n'est effectuée vers un nom d'hôte qui se résout en une telle adresse.
  • Les redirections ne sont pas suivies. Une réponse 3xx compte comme une livraison échouée; utilisez donc l'adresse finale comme URL de votre webhook.
  • Lorsque 20 webhooks consécutifs pour un site échouent à chaque nouvelle tentative, les webhooks de ce site sont mis en pause. Pendant la pause, les nouveaux webhooks ne sont pas envoyés, et ils ne sont pas envoyés plus tard non plus. Communiquez avec le soutien pour les reprendre une fois votre point de terminaison corrigé.