Webhooks

Un site web peut avoir jusqu'à cinq webhooks. Une fois configuré, Hyvor Talk enverra une requête HTTP POST à cette URL lors de certains événements (ex. : lorsqu'un nouveau commentaire est créé). Vous pouvez agir sur ces événements (ex. : envoyer un e-mail à l'auteur du commentaire). Veillez à valider les requêtes de webhook pour vous assurer qu'elles proviennent bien de Hyvor Talk.

Configurer les webhooks

Vous pouvez configurer les webhooks dans Console → Paramètres → Webhooks → Ajouter un webhook. Vous pouvez sélectionner n'importe quel événement, et chaque webhook peut s'abonner à un nombre quelconque d'événements.

• L'URL doit être accessible publiquement
• Utilisez https (fortement recommandé)

Réponse

Pour chaque requête de webhook, nous attendons de votre serveur un code de réponse 200 OK. Si la requête échoue (nous recevons un autre code de réponse), nous réessaierons deux fois de plus. Ensuite, nous marquerons la requête de webhook comme échouée et cesserons d'envoyer d'autres requêtes pour cet événement.

Requête HTTP POST

Le corps de la requête est une chaîne encodée en JSON avec la structure de données suivante.

{
	"event": "comment.create",
	"data": {} // un objet
}

Événements et données

Le champ event et le champ data diffèrent selon le type d'événement. Voici la liste de tous les types d'événements et de leurs données.

Valider les webhooks

Dans les paramètres des webhooks, veillez à générer une clé secrète. Elle sera utilisée pour signer les requêtes de webhook. Vous pourrez ensuite vérifier la signature de la requête pour vous assurer qu'elle provient bien de Hyvor Talk. La signature est un hash HMAC-SHA256 du corps JSON de la requête. La clé secrète est utilisée comme clé. Pour valider, vous devez générer une signature avec le même algorithme, le corps de requête fourni et la clé secrète. Ensuite, comparez la signature générée avec la signature de l'en-tête X-Signature. Si elles correspondent, la requête est valide.

Voici un exemple en PHP de validation de la signature.

// récupérer le corps complet de la requête sous forme de chaîne
$requestBody = file_get_contents('php://input');

// générer la signature à comparer
$signature = hash_hmac('sha256', $requestBody, $secretKey);

// signature fournie dans l'en-tête X-Signature
$givenSignature = $_SERVER['HTTP_X_SIGNATURE'];

if (hash_equals($signature, $givenSignature)) {
    // valide
} else {
    // invalide
}

IP de confiance (liste blanche d'IP)

Les requêtes de webhook transitent par deux adresses IP :

• 78.47.223.80
• 2a01:4f8:1c17:b1d7::

Pour plus de sécurité, vous pouvez mettre ces adresses sur liste blanche pour le trafic HTTPS entrant (port 443) vers votre point de terminaison de webhook. Cependant, la liste blanche d'IP est facultative et ne doit pas remplacer la vérification de la signature.