Les bonnes pratiques

​

Code HTTP 2xx

L’URL de destination d’un webhook doit toujours renvoyer un code HTTP 2XX.

Il s’agit de s’assurer que la communication se soit bien passée. Les erreurs métier ne doivent pas être gérés avec les codes d’erreur HTTP.

​

Délais de réponse

L’URL de destination doit répondre rapidement. Un délai de réponse de moins de 500ms est attendu.

Un délai gracieux de moins d’une seconde peut être permis dans des cas de figure exceptionnels.

Ceci maintient une qualité de service optimale. Les webhooks live avec des délais de réponse supérieurs ne seront pas autorisés.

​

Gestion asynchrone

Afin de parvenir à ces temps de réponses, il existe des mécanismes simples qui peuvent être mis en place. Entre autres, il est fortement encouragé de traiter les webhooks de façon asynchrone à leur reception et d’immédiatement renvoyer un code HTTP 2xx.

Exemple en javascript:

async function onPaymentIntentCreatedWebhookReceived(req, res) {
   await this.verifyHub2WebhookSignature(req);
   this.handlePaymentIntentCreated(req); // async method, event queue ...
   res.send('""');
   res.status(201).end(); // Send HTTP 2xx right away
}

​

Répartition des événements par webhook

Si un seul webhook est enregistré avec l’ensemble des événements, sa désactivation privera l’URL distante de notifications sur l’ensemble des événements.

Une bonne pratique pour éviter ce comportement est d’enregistrer un seul événement par webhook, de sorte qu’une désactivation n’impacte qu’un seul événement et n’aura pas d’impact sur les autres webhooks enregistrés sur les autres événements.