Avec FastComments, il est possible d'appeler un point de terminaison d'API chaque fois qu'un commentaire est ajouté, mis à jour ou supprimé de notre système.
Nous y parvenons grâce à des webhooks asynchrones via HTTP/HTTPS.
Qu'est-ce qu'un webhook ? 
Un Webhook est un mécanisme, ou une intégration, entre deux systèmes où le "producteur" (FastComments) déclenche un événement que le "consommateur" (Vous) consomme via un appel d'API.
Événements et ressources pris en charge
FastComments prend en charge les webhooks uniquement pour la ressource Comment.
Nous prenons en charge les webhooks pour la création, la suppression et la mise à jour des commentaires.
Chacun d'entre eux est considéré comme un événement distinct dans notre système et, en tant que tel, possède des sémantiques différentes et des structures différentes pour les événements webhook.
Configuration pour le développement local
Pour le développement local, utilisez un outil tel que ngrok.
Afin de faciliter la sécurité du système, le développement local suit le même processus que la configuration et la sécurisation des autres environnements.
Étape 1 : Ajoutez "localhost" aux domaines de votre compte.
Ajoutez "localhost" comme domaine ici.
Étape 2 : Choisissez une clé API
Nous allons ajouter une configuration de webhook pour votre domaine, donc nous aurons besoin d'une clé API. Vous pouvez le faire ici.
Under "Associate with domain" - select your "localhost" domain.
REMARQUE : Alternativement, vous pouvez utiliser un seul secret API pour toute l'activité de test et les environnements de préproduction. Ajoutez simplement un secret API pour "All Domains", et donnez-lui un nom comme "test".
Assurez-vous d'avoir un secret API défini pour vos domaines de production. Les événements pour tous les autres domaines utiliseront le secret générique (de test).
Étape 3 : Ajoutez votre webhook
Pendant que vous exécutez ngrok ou un outil similaire, définissez la valeur pour "localhost" ici.
When clicking Send Test Payload, we will send two test events to check that you validate the API key.
Une fois validée, cliquez sur Save.
Étape 4 : Ajoutez un commentaire
Maintenant, vous pouvez ajouter, modifier ou supprimer des commentaires et vous devriez nous voir appeler votre machine de développement locale avec les événements, en utilisant votre clé API de test. Il peut y avoir un délai pouvant aller jusqu'à 30 secondes avant que les événements n'atteignent votre machine.
Configuration
Suivez les mêmes étapes pour localhost que pour la production. Assurez-vous d'avoir configuré des domaines de production et des API Secrets.
First, navigate to the Administration des webhooks. This is accessible via Gérer les données -> Webhooks.
The configuration page appears as follows:
On this page you can specify endpoints for each type of comment event.
For each type of event, be sure to click Send Test Payload to ensure you've set up your integration correctly. See the next section, "Tests", for details.
Tests
Dans l'administration Webhooks il y a des boutons Send Test Payload pour chaque type d'événement (Create, Update, Delete). Les événements Create et Update envoient un objet WebhookComment factice, tandis que le test Delete enverra un corps de requête factice contenant juste un ID.
Vérification des charges utiles
Lorsque vous testez votre intégration de webhook, vérifiez que les requêtes entrantes incluent les en-têtes suivants :
token- Votre secret APIX-FastComments-Timestamp- horodatage Unix (secondes)X-FastComments-Signature- signature HMAC-SHA256
Utilisez la vérification de la signature HMAC pour garantir que les charges utiles sont authentiques.
Outils de test
Vous pouvez utiliser des outils comme webhook.site ou ngrok pour inspecter les charges utiles entrantes des webhooks pendant le développement.
Types d'événements
- Create Event: Déclenché lorsqu'un nouveau commentaire est créé. Méthode par défaut : PUT
- Update Event: Déclenché lorsqu'un commentaire est édité. Méthode par défaut : PUT
- Delete Event: Déclenché lorsqu'un commentaire est supprimé. Méthode par défaut : DELETE
Chaque événement inclut l'ensemble des données du commentaire dans le corps de la requête (voir Structures de données pour le format de la charge utile).
Structures de données
La seule structure envoyée via les webhooks est l'objet WebhookComment, décrit en TypeScript ci-dessous.
Structure de l'objet WebhookComment
Structure de l'événement "Create"
Le corps de la requête pour l'événement "create" est un objet WebhookComment.
Structure de l'événement "Update"
Le corps de la requête pour l'événement "update" est un objet WebhookComment.
Structure de l'événement "Delete"
Le corps de la requête pour l'événement "delete" est un objet WebhookComment.
Change as of Nov 14th 2023
Previously the "delete" event request body only contained the comment id. It now contains the full comment at the time of deletion.
Run Lorsque des utilisateurs sont tagués dans un commentaire, l'information est stockée dans une liste appelée mentions. Chaque objet de cette liste a la structure suivante.
Run Méthodes HTTP
Vous pouvez configurer la méthode HTTP pour chaque type d'événement webhook dans le panneau d'administration :
- Create Event: POST or PUT (default: PUT)
- Update Event: POST or PUT (default: PUT)
- Delete Event: DELETE, POST, or PUT (default: DELETE)
Since all requests contain an ID, Create and Update operations are idempotent by default (PUT). Repeating the same Create or Update request should not create duplicate objects on your side.
En-têtes de requête
Chaque requête webhook inclut les en-têtes suivants :
| En-tête | Description |
|---|---|
Content-Type |
application/json |
token |
Votre secret d'API |
X-FastComments-Timestamp |
Horodatage Unix (secondes) correspondant au moment de la signature de la requête |
X-FastComments-Signature |
Signature HMAC-SHA256 (sha256=<hex>) |
Voir Sécurité & jetons d'API pour obtenir des informations sur la vérification de la signature HMAC.
Sécurité et jetons d'API
Les requêtes webhook FastComments incluent plusieurs mécanismes d'authentification pour la sécurité.
En-têtes envoyés
| En-tête | Description |
|---|---|
token |
Votre Secret d'API (pour compatibilité ascendante) |
X-FastComments-Timestamp |
Horodatage Unix (secondes) indiquant quand la requête a été signée |
X-FastComments-Signature |
Signature HMAC-SHA256 de la charge utile |
Vérification de la signature HMAC (recommandée)
Nous recommandons fortement de vérifier la signature HMAC pour garantir que les charges utiles des webhooks sont authentiques et n'ont pas été altérées.
Format de la signature : sha256=<hex-encoded-signature>
Comment la signature est calculée :
- Concaténez :
timestamp + "." + JSON_payload_body - Calculez le HMAC-SHA256 en utilisant votre Secret d'API comme clé
- Encodez le résultat en hexadécimal
Exemple de vérification (Node.js)
const crypto = require('crypto');
function verifyWebhookSignature(req, apiSecret) {
const timestamp = req.headers['x-fastcomments-timestamp'];
const signature = req.headers['x-fastcomments-signature'];
if (!timestamp || !signature) {
return false;
}
// Vérifier que l'horodatage est récent (moins de 5 minutes)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return false; // Prévention des attaques par rejeu
}
// Vérifier la signature
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', apiSecret)
.update(`${timestamp}.${payload}`)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Exemple de vérification (Python)
import hmac
import hashlib
import time
import json
def verify_webhook_signature(headers, body, api_secret):
timestamp = headers.get('X-FastComments-Timestamp')
signature = headers.get('X-FastComments-Signature')
if not timestamp or not signature:
return False
# Vérifier que l'horodatage est récent
now = int(time.time())
if abs(now - int(timestamp)) > 300:
return False
# Vérifier la signature
payload = json.dumps(body, separators=(',', ':'))
message = f"{timestamp}.{payload}"
expected = hmac.new(
api_secret.encode(),
message.encode(),
hashlib.sha256
).hexdigest()
return signature == f"sha256={expected}"Exemple de vérification (PHP)
function verifyWebhookSignature($headers, $body, $apiSecret) {
$timestamp = $headers['X-FastComments-Timestamp'] ?? null;
$signature = $headers['X-FastComments-Signature'] ?? null;
if (!$timestamp || !$signature) {
return false;
}
// Vérifier que l'horodatage est récent (moins de 5 minutes)
$now = time();
if (abs($now - intval($timestamp)) > 300) {
return false;
}
// Vérifier la signature
$payload = json_encode($body, JSON_UNESCAPED_SLASHES);
$message = $timestamp . '.' . $payload;
$expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);
return hash_equals($expectedSignature, $signature);
}Authentification héritée
L'en-tête token contenant votre Secret d'API est toujours envoyé pour assurer la compatibilité ascendante. Cependant, nous recommandons de migrer vers la vérification HMAC pour une sécurité renforcée, car elle protège contre les attaques par rejeu.
Fonctionnement et gestion des réessais
Tous les changements apportés à l'objet Comment dans le système déclenchent un événement qui finit dans une file d'attente.
L'événement webhook initial est généralement envoyé dans les six secondes suivant la survenue de la source de l'événement.
Vous pouvez surveiller cette file d'attente dans l'administration des Webhooks au cas où votre API tomberait en panne.
Si une requête vers votre API échoue, nous la remettrons en file d'attente selon un calendrier.
That schedule is 1 Minute * the retry count. Si l'appel échoue une fois, il réessaiera dans
une minute. S'il échoue deux fois, il attendra alors deux minutes, et ainsi de suite. Cela permet de
ne pas surcharger votre API si elle tombe en panne pour des raisons liées à la charge.
Les webhooks peuvent être annulés depuis la page des journaux.
En conclusion
Cela conclut notre documentation sur les Webhooks.
Nous espérons que vous trouverez l'intégration Webhook de FastComments facile à comprendre et rapide à configurer.
Si vous pensez avoir identifié des lacunes dans notre documentation, faites-nous savoir ci-dessous.