Con FastComments è possibile invocare un endpoint API ogni volta che un commento viene aggiunto, aggiornato o rimosso dal nostro sistema.
Realizziamo questo tramite webhook asincroni su HTTP/HTTPS.
Cosa sono i Webhook 
Un Webhook è un meccanismo, o un'integrazione, tra due sistemi in cui il "produttore" (FastComments) scatena un evento che il "consumatore" (tu) consuma tramite una chiamata API.
Eventi e risorse supportati
FastComments supporta i webhook solo per la risorsa Comment.
Supportiamo webhook per la creazione, la rimozione e l'aggiornamento dei commenti.
Ognuno di questi è considerato un evento separato nel nostro sistema e, come tale, ha semantiche diverse e strutture diverse per gli eventi webhook.
Configurazione per sviluppo locale
Per lo sviluppo locale, usa uno strumento come ngrok.
Per semplificare il mantenimento della sicurezza del sistema, lo sviluppo locale segue lo stesso processo di configurazione e protezione degli altri ambienti.
Passo 1: Aggiungi "localhost" ai domini del tuo account.
Aggiungi "localhost" come dominio qui.
Passo 2: Scegli una chiave API
Aggiungeremo una configurazione webhook per il tuo dominio, quindi avremo bisogno di una chiave API. Puoi farlo qui.
Under "Associate with domain" - select your "localhost" domain.
NOTA: In alternativa, puoi usare un unico API Secret per tutte le attività di test e gli ambienti di staging. Aggiungi semplicemente un API Secret per "All Domains", e dagli un nome come "test".
Assicurati di avere un API Secret definito per i tuoi domini di produzione. Gli eventi per tutti gli altri domini useranno il secret wildcard (di test).
Passo 3: Aggiungi il tuo Webhook
Mentre esegui ngrok o uno strumento simile, imposta il valore per "localhost" qui.
Cliccando Send Test Payload, invieremo due eventi di prova per verificare che la chiave API venga validata correttamente.
Una volta validata, premi Save.
Passo 4: Aggiungi un commento
Ora puoi aggiungere, modificare o eliminare commenti e dovresti vedere che chiamiamo la tua macchina di sviluppo locale con gli eventi, utilizzando la tua chiave API di test. Potrebbero esserci fino a 30 secondi di ritardo perché gli eventi raggiungano la tua macchina.
Configurazione
Segui gli stessi passaggi per localhost che faresti per la produzione. Assicurati di avere configurato i domini di produzione e gli API Secrets.
Per prima cosa, vai al Pannello Webhooks. È accessibile tramite Gestisci dati -> Webhooks.
La pagina di configurazione appare come segue:
In questa pagina puoi specificare gli endpoint per ogni tipo di evento di commento.
Per ogni tipo di evento, assicurati di cliccare Invia payload di test per verificare di aver configurato correttamente l'integrazione. Consulta la sezione successiva, "Test", per i dettagli.
Test
Nella Webhooks admin ci sono Send Test Payload buttons per ogni tipo di evento (Create, Update, Delete). Gli eventi Create e Update inviano un oggetto di prova WebhookComment, mentre il test di Delete invierà un corpo della richiesta fittizio contenente solo un ID.
Verifica dei payload
Quando testi la tua integrazione webhook, verifica che le richieste in arrivo includano le seguenti intestazioni:
token- Il tuo API SecretX-FastComments-Timestamp- Unix timestamp (secondi)X-FastComments-Signature- HMAC-SHA256 signature
Usa la verifica della firma HMAC per garantire che i payload siano autentici.
Strumenti di test
Puoi usare strumenti come webhook.site o ngrok per ispezionare i payload webhook in arrivo durante lo sviluppo.
Tipi di evento
- Create Event: Scatenato quando viene creato un nuovo commento. Metodo predefinito: PUT
- Update Event: Scatenato quando un commento viene modificato. Metodo predefinito: PUT
- Delete Event: Scatenato quando un commento viene eliminato. Metodo predefinito: DELETE
Ogni evento include tutti i dati del commento nel corpo della richiesta (vedi Strutture dei dati per il formato del payload).
Strutture dati
L'unica struttura inviata tramite webhook è l'oggetto WebhookComment, descritto in TypeScript qui sotto.
La struttura dell'oggetto WebhookComment
La "Create" Event Structure
Il body della richiesta dell'evento "create" è un oggetto WebhookComment.
La "Update" Event Structure
Il body della richiesta dell'evento "update" è un oggetto WebhookComment.
La "Delete" Event Structure
Il body della richiesta dell'evento "delete" è un oggetto WebhookComment.
Modifica a partire dal 14 Nov 2023
In precedenza il body della richiesta dell'evento "delete" conteneva solo l'id del commento. Ora contiene il commento completo al momento dell'eliminazione.
Run When users are tagged in a comment, the information is stored in a list called mentions. Each object in that list
has the following structure.
Run HTTP Methods
Puoi configurare il metodo HTTP per ciascun tipo di evento webhook nel pannello di amministrazione:
- Evento "Create": POST o PUT (predefinito: PUT)
- Evento "Update": POST o PUT (predefinito: PUT)
- Evento "Delete": DELETE, POST o PUT (predefinito: DELETE)
Poiché tutte le richieste contengono un ID, le operazioni Create e Update sono idempotenti per impostazione predefinita (PUT). Ripetere la stessa richiesta di Create o Update non dovrebbe creare oggetti duplicati dalla tua parte.
Request Headers
Ogni richiesta webhook include le seguenti intestazioni:
| Header | Descrizione |
|---|---|
Content-Type |
application/json |
token |
Il tuo API Secret |
X-FastComments-Timestamp |
Timestamp Unix (secondi) quando la richiesta è stata firmata |
X-FastComments-Signature |
Firma HMAC-SHA256 (sha256=<hex>) |
Vedi Sicurezza e token API per informazioni sulla verifica della firma HMAC.
Sicurezza e token API
FastComments webhook requests include multiple authentication mechanisms for security.
Intestazioni inviate
| Intestazione | Descrizione |
|---|---|
token |
Il tuo API Secret (per compatibilità con le versioni precedenti) |
X-FastComments-Timestamp |
Timestamp Unix (secondi) quando la richiesta è stata firmata |
X-FastComments-Signature |
Firma HMAC-SHA256 del payload |
Verifica della firma HMAC (Consigliata)
Raccomandiamo vivamente di verificare la firma HMAC per assicurarsi che i payload dei webhook siano autentici e non siano stati manomessi.
Formato della firma: sha256=<hex-encoded-signature>
Come viene calcolata la firma:
- Concatena:
timestamp + "." + JSON_payload_body - Calcola HMAC-SHA256 usando il tuo API Secret come chiave
- Codifica il risultato in esadecimale
Esempio di verifica (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;
}
// Verifica che il timestamp sia recente (entro 5 minuti)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return false; // Prevenzione di attacchi di replay
}
// Verifica della firma
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', apiSecret)
.update(`${timestamp}.${payload}`)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Esempio di verifica (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
# Verifica che il timestamp sia recente
now = int(time.time())
if abs(now - int(timestamp)) > 300:
return False
# Verifica la firma
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}"Esempio di verifica (PHP)
function verifyWebhookSignature($headers, $body, $apiSecret) {
$timestamp = $headers['X-FastComments-Timestamp'] ?? null;
$signature = $headers['X-FastComments-Signature'] ?? null;
if (!$timestamp || !$signature) {
return false;
}
// Verifica che il timestamp sia recente (entro 5 minuti)
$now = time();
if (abs($now - intval($timestamp)) > 300) {
return false;
}
// Verifica la firma
$payload = json_encode($body, JSON_UNESCAPED_SLASHES);
$message = $timestamp . '.' . $payload;
$expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);
return hash_equals($expectedSignature, $signature);
}Autenticazione legacy
L'intestazione token contenente il tuo API Secret viene ancora inviata per compatibilità con le versioni precedenti. Tuttavia, consigliamo di migrare alla verifica HMAC per una sicurezza migliorata poiché protegge dagli attacchi di replay.
Come funziona e gestione dei tentativi di ritrasmissione
Tutte le modifiche all'oggetto Comment nel sistema generano un evento che finisce in una coda.
L'evento webhook iniziale viene solitamente inviato entro sei secondi dall'occorrenza della sorgente dell'evento.
Puoi monitorare questa coda nell'amministrazione Webhooks nel caso in cui la tua API vada offline.
Se una richiesta alla tua API fallisce, la rimetteremo in coda secondo una pianificazione.
Quella pianificazione è 1 Minute * the retry count. Se la chiamata fallisce una volta, riproverà in
un minuto. Se fallisce due volte, allora aspetterà due minuti, e così via. Questo serve a evitare che
sovraccarichiamo la tua API se stai andando offline per motivi legati al carico.
I Webhooks possono essere annullati dalla pagina dei log.
In conclusione
Questa conclude la nostra documentazione sui Webhooks.
Speriamo che troviate l'integrazione FastComments Webhook facile da comprendere e veloce da configurare.
Se ritenete di aver individuato delle lacune nella nostra documentazione, fatecelo sapere qui sotto.