Webhooks
Con FastComments es posible invocar un endpoint de la API cada vez que se añade, actualiza o elimina un comentario de nuestro sistema.
Lo logramos con webhooks asíncronos a través de HTTP/HTTPS.
Qué son los webhooks 
Un Webhook es un mecanismo, o una integración, entre dos sistemas donde el "productor" (FastComments) desencadena un evento que el "consumidor" (Usted) consume mediante una llamada a la API.
Eventos y recursos compatibles
FastComments admite webhooks solo para el recurso Comment.
Admitimos webhooks para la creación, eliminación y actualización de comentarios.
Cada uno de ellos se considera un evento separado en nuestro sistema y, por lo tanto, tiene distintas semánticas y estructuras para los eventos de webhook.
Configuración de desarrollo local
For Local development, use a tool like ngrok.
In order to simplify keeping the system secure, local development follows the same process as setting up and securing other environments.
Step 1: Add "localhost" to domains in your account.
Add "localhost" como dominio aquí.
Step 2: Pick an API Key
We're going to be adding webhook configuration for your domain, so we'll need an API key. Puedes hacerlo aquí.
Under "Associate with domain" - select your "localhost" domain.
NOTA: Alternatively, you can use one API Secret for all testing activity and staging environments. Simply add an API Secret for "All Domains", and give it a name like "test".
Ensure you have an API Secret defined for your production domain(s). Events for all other domains will use the wildcard (testing) secret.
Step 3: Add Your Webhook
While running ngrok or similar tool, set the value for "localhost" aquí.
When clicking Send Test Payload, we will send two test events to check that you validate the API key.
Once it validates, hit Save.
Step 4: Add A Comment
Now you can add, edit, or delete comments and should see us call your local development machine with the events, using your testing API key. There may be up to 30 seconds delay for the events to reach your machine.
Configuración
Siga los mismos pasos para localhost como lo haría en producción. Asegúrese de que tiene dominios de producción y secretos de API configurados.
Primero, navegue a la administración de Webhooks. Esto es accesible a través de Administrar datos -> Webhooks.
La página de configuración aparece de la siguiente manera:
En esta página puede especificar endpoints para cada tipo de evento de comentario.
Para cada tipo de evento, asegúrese de hacer clic en Enviar carga de prueba para garantizar que ha configurado su integración correctamente. Consulte la siguiente sección, "Testing", para obtener más detalles.
Pruebas
En la administración de Webhooks hay botones Send Test Payload para cada tipo de evento (Create, Update, Delete). Los eventos Create y Update envían un objeto WebhookComment de prueba, mientras que al probar Delete se enviará un cuerpo de solicitud de prueba con solo un ID.
Verificar cargas útiles
Al probar la integración de tu webhook, verifica que las solicitudes entrantes incluyan los siguientes encabezados:
token- Tu secreto de APIX-FastComments-Timestamp- Marca de tiempo Unix (segundos)X-FastComments-Signature- Firma HMAC-SHA256
Utiliza la verificación de la firma HMAC para garantizar que las cargas útiles sean auténticas.
Herramientas de prueba
Puedes usar herramientas como webhook.site o ngrok para inspeccionar las cargas útiles entrantes de los webhooks durante el desarrollo.
Tipos de eventos
- Create Event: Se desencadena cuando se crea un nuevo comentario. Método predeterminado: PUT
- Update Event: Se desencadena cuando se edita un comentario. Método predeterminado: PUT
- Delete Event: Se desencadena cuando se elimina un comentario. Método predeterminado: DELETE
Cada evento incluye los datos completos del comentario en el cuerpo de la solicitud (consulta Estructuras de datos para el formato de la carga útil).
Estructuras de datos
La única estructura enviada vía webhooks es el objeto WebhookComment, descrito en TypeScript a continuación.
Estructura del objeto WebhookComment
Estructura del evento "Create"
El cuerpo de la solicitud del evento "create" es un objeto WebhookComment.
Estructura del evento "Update"
El cuerpo de la solicitud del evento "update" es un objeto WebhookComment.
Estructura del evento "Delete"
El cuerpo de la solicitud del evento "delete" es un objeto WebhookComment.
Cambio a partir del 14 de noviembre de 2023
Anteriormente, el cuerpo de la solicitud del evento "delete" solo contenía el id del comentario. Ahora contiene el comentario completo en el momento de la eliminación.
Run Cuando los usuarios son etiquetados en un comentario, la información se almacena en una lista llamada mentions. Cada objeto en esa lista
tiene la siguiente estructura.
Run Métodos HTTP
Puede configurar el método HTTP para cada tipo de evento de webhook en el panel de administración:
- Create Event: POST o PUT (predeterminado: PUT)
- Update Event: POST o PUT (predeterminado: PUT)
- Delete Event: DELETE, POST o PUT (predeterminado: DELETE)
Dado que todas las solicitudes contienen un ID, las operaciones Create y Update son idempotentes por defecto (PUT). Repetir la misma solicitud Create o Update no debería crear objetos duplicados en su lado.
Encabezados de la solicitud
Cada solicitud de webhook incluye los siguientes encabezados:
| Header | Description |
|---|---|
Content-Type | application/json |
token | Su API Secret |
X-FastComments-Timestamp | Marca de tiempo Unix (segundos) cuando se firmó la solicitud |
X-FastComments-Signature | Firma HMAC-SHA256 (sha256=<hex>) |
Consulte Seguridad y tokens de API para obtener información sobre la verificación de la firma HMAC.
Seguridad y tokens de API
Las solicitudes webhook de FastComments incluyen múltiples mecanismos de autenticación por motivos de seguridad.
Encabezados enviados
| Header | Description |
|---|---|
token | Tu API Secret (para compatibilidad con versiones anteriores) |
X-FastComments-Timestamp | Marca de tiempo Unix (segundos) cuando se firmó la solicitud |
X-FastComments-Signature | Firma HMAC-SHA256 de la carga útil |
Verificación de firma HMAC (Recomendado)
Recomendamos encarecidamente verificar la firma HMAC para garantizar que las cargas útiles de los webhooks sean auténticas y no hayan sido manipuladas.
Formato de la firma: sha256=<hex-encoded-signature>
Cómo se calcula la firma:
- Concatenar:
timestamp + "." + JSON_payload_body - Calcular HMAC-SHA256 usando tu API Secret como clave
- Codificar el resultado en hexadecimal
Ejemplo de verificación (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;
}
// Verificar que la marca de tiempo sea reciente (dentro de 5 minutos)
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(timestamp, 10)) > 300) {
return false; // Prevención de ataques de repetición
}
// Verificar firma
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
.createHmac('sha256', apiSecret)
.update(`${timestamp}.${payload}`)
.digest('hex');
return signature === `sha256=${expectedSignature}`;
}Ejemplo de verificación (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
# Verificar que la marca de tiempo sea reciente
now = int(time.time())
if abs(now - int(timestamp)) > 300:
return False
# Verificar 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}"Ejemplo de verificación (PHP)
function verifyWebhookSignature($headers, $body, $apiSecret) {
$timestamp = $headers['X-FastComments-Timestamp'] ?? null;
$signature = $headers['X-FastComments-Signature'] ?? null;
if (!$timestamp || !$signature) {
return false;
}
// Verificar que la marca de tiempo sea reciente (dentro de 5 minutos)
$now = time();
if (abs($now - intval($timestamp)) > 300) {
return false;
}
// Verificar firma
$payload = json_encode($body, JSON_UNESCAPED_SLASHES);
$message = $timestamp . '.' . $payload;
$expectedSignature = 'sha256=' . hash_hmac('sha256', $message, $apiSecret);
return hash_equals($expectedSignature, $signature);
}Autenticación heredada
El encabezado token que contiene tu API Secret todavía se envía por compatibilidad con versiones anteriores. Sin embargo, recomendamos migrar a la verificación HMAC para mejorar la seguridad, ya que protege contra ataques de repetición.
Funcionamiento y gestión de reintentos
Todos los cambios en el objeto Comment en el sistema disparan un evento que termina en una cola.
El evento webhook inicial suele enviarse dentro de seis segundos desde que ocurre la fuente del evento.
Puedes supervisar esta cola en el panel de administración de Webhooks en caso de que tu API se caiga.
Si una solicitud a tu API falla, la volveremos a encolar según un programa.
Ese programa es 1 Minute * the retry count. Si la llamada falla una vez, intentará de nuevo en
un minuto. Si falla dos veces, esperará entonces dos minutos, y así sucesivamente. Esto es para que no
sobrecarguemos tu API si estáis cayendo por razones relacionadas con la carga.
Los webhooks pueden cancelarse desde la página de registros.
En conclusión
Esto concluye nuestra documentación de Webhooks.
Esperamos que la integración de Webhooks de FastComments le resulte fácil de entender y rápida de configurar.
Si considera que ha identificado alguna laguna en nuestra documentación, háganoslo saber a continuación.