Webhooks

Les webhooks sont la porte d'entrée de votre back office vers le monde extérieur. Ils vous permettent d'intéragir avec d'autres applications via un système d'évènements. Au même titre que l'API de votre back office, c'est un élément essentiel pour constituer vos flux de travail.

Composition

Un point d'entrée de webhook est composé d'une URL unique, d'une méthode, d'une clé secrète et d'un ensemble d'évènements.

Les méthodes de requête possibles sont :

• DELETE
• GET
• PATCH
• POST
• PUT

Les évènements sont l'ensemble des actions qui vont déclencher un appel vers l'URL du webhook, par exemple, ajouter un utilisateur, éditer une tâche, supprimer un fichier etc.

Requêtes

Chaque évènement sur votre back office déclenche une requête de webhook si ce dernier a été configuré. Une requête de webhook contient plusieurs informations provenant du back office :

• le contenu représentant la ressource au format JSON
• l'évènement au format ressource.action, par exemple user.create
• la clé secrète dans l'en-tête de requête x-backoffice-signature

Voici un exemple de contenu envoyé par votre webhook :

{
  "event": "user.create",
  "payload": {
    "id": "6fb779a9-d615-4d1b-be5f-78421977acb2",
    "email": "[email protected]"
  }
}

Une fois la requête effectuée, son résultat est persisté via deux champs :

• le corps de réponse qui contient la réponse de la requête au format JSON
• le code de réponse qui contient le code de réponse de la requête

En cas d'échec de la requête, il est possible de réessayer cette dernière.

Sécurité

⚠️

Afin de garantir la sécurité de votre webhook, il est conseillé de mettre en place ces quelques actions :

• Utiliser la méthode POST pour vos webhooks
• Utiliser le protocole HTTPS pour l'URL de vos webhooks
• Authentifier la clé secrète via l'en-tête x-backoffice-signature

Cas pratique

Imaginez que vous souhaitiez envoyer un e-mail à chaque fois qu'une tâche est complétée. Pour ce faire, vous allez combiner les webhooks avec un service d'automatisation tel que Zapier. Simplement, vous créez un nouveau zap sur Zapier en deux étapes :

1. Catch hook
2. Send email

Vous obtenez alors votre URL de point d'entrée webhook : https://hooks.zapier.com/hooks/catch/1.

Il vous suffit alors de créer un nouveau webhook avec les paramètres suivants :

• URL : https://hooks.zapier.com/hooks/catch/1
• Méthode : POST
• Évènements : Compléter Tâche

Et voilà ! 🎉 Votre automatisation a été mise en place en deux étapes simples.