Webhooks
Los webhooks envían una solicitud a tu servidor cuando algo cambia en tu centro de ayuda, por ejemplo, cuando se publica un artículo, un lector deja sus comentarios o se completa una tarea de Fern. Úsalos para reconstruir un índice de búsqueda, sincronizar artículos con tu producto o publicar en un canal del equipo.
Los propietarios y administradores añaden endpoints en Settings > Workspace > Developers, en Webhooks. Un desarrollador también puede gestionarlos con una clave de API que tenga el alcance webhooks:manage.
Eventos
Evento | Se envía cuando |
|---|---|
| Se publica un artículo, incluida cada republicación de un artículo activo. Las ediciones de contenido se envían como una nueva publicación. |
| Cambia el slug, la configuración de SEO o la ubicación de un artículo activo. Las ediciones de borradores no generan ningún envío. |
| Se retira la publicación de un artículo. |
| Se elimina un artículo y, una vez por cada artículo, cuando se elimina una colección. Los artículos eliminados se pueden restaurar durante 30 días. |
| Se restaura un artículo eliminado. |
| Se publica una traducción. |
| Una entrada del registro de cambios se publica por primera vez. Las ediciones posteriores no vuelven a generar el envío. Cada publicación de una entrada también envía |
| Un lector califica un artículo o deja un comentario. |
| Se publica la revisión de una tarea de Fern y la tarea se completa. |
Suscríbete a * para recibir todos los eventos.
La solicitud
Ferndesk envía una solicitud POST con un cuerpo JSON a tu endpoint HTTPS. Todos los eventos tienen el mismo envoltorio, y data depende del evento.
{
"id": "whevt_01JZ8M3Q7T2K9V4X6B1N5C8D0E",
"type": "article.published",
"created_at": "2026-11-21T10:15:00.000Z",
"data": {
"id": "art_01JZ8M2W4R6T8Y0U2I4O6P8A1S",
"title": "Reset your password",
"slug": "reset-your-password",
"status": "published",
"version": 4,
"url": "https://help.example.com/reset-your-password-ab12c",
"collection_id": "col_01JZ8M1E3R5T7Y9U1I3O5P7A9S",
"published_by_member_id": "mem_01JZ8M0Q2W4E6R8T0Y2U4I6O8P",
"source": "editor"
}
}Evento | Campos de data |
|---|---|
eventos de artículos |
|
|
|
|
|
|
|
|
|
Si el cuerpo supera los 256 KB, se envía con data sustituido por {"truncated": true}. Obtén el objeto mediante la API.
Encuentra tu secreto de firma
Cada webhook tiene su propio secreto de firma, que empieza por whsec_. Los propietarios y administradores lo encuentran al editar el webhook en Settings > Workspace > Developers > Webhooks. Permanece oculto hasta que selecciones Revelar en su menú. Copiar lo copia sin mostrarlo. Al añadir un webhook, el cuadro de diálogo permanece abierto para que puedas copiar el nuevo secreto enseguida.
Un webhook creado con POST /webhooks recibe su secreto una sola vez, en la respuesta. También puedes encontrarlo más tarde en la aplicación.
Verifica la firma
Ferndesk firma cada solicitud con el esquema Standard Webhooks, el mismo que usa Svix. Cada solicitud tiene tres encabezados:
Encabezado | Valor |
|---|---|
| El ID del evento ( |
| La hora Unix en segundos en que se envió este intento. Cada reintento se firma de nuevo con una marca de tiempo nueva. |
| Uno o más valores |
Lee el cuerpo sin procesar de la solicitud antes de analizarlo. Un cuerpo que se haya analizado y convertido de nuevo a JSON no coincidirá.
Crea el texto firmado: el valor de
webhook-id, un punto, el valor dewebhook-timestamp, un punto y, a continuación, el cuerpo sin procesar.Elimina
whsec_del secreto y decodifica el resto en base64. Esa es la clave.Calcula el HMAC-SHA256 del texto firmado con la clave y codifícalo en base64.
Compáralo con cada valor
v1dewebhook-signaturemediante una comparación de tiempo constante. Acepta la solicitud si alguno coincide.Rechaza la solicitud si
webhook-timestampdifiere en más de 5 minutos de la hora de tu servidor. Esto impide que se vuelvan a enviar solicitudes antiguas.
La forma más sencilla es usar la biblioteca Standard Webhooks o Svix, que se encarga de todo esto, incluida la comprobación de la marca de tiempo. Con Svix (npm install svix), verify genera un error si la firma o la marca de tiempo no son correctas. La segunda pestaña realiza las mismas comprobaciones usando únicamente node:crypto.
import express from 'express';
import { Webhook } from 'svix';
const app = express();
const webhook = new Webhook(process.env.FERNDESK_WEBHOOK_SECRET);
app.post('/webhooks/ferndesk', express.raw({ type: 'application/json' }), (req, res) => {
try {
webhook.verify(req.body, req.headers);
} catch {
return res.status(400).send('Invalid signature');
}
const event = JSON.parse(req.body.toString('utf8'));
res.sendStatus(200);
});
app.listen(3000);Rota el secreto
Selecciona Rotar en el menú del secreto de firma. El nuevo secreto entra en vigor de inmediato. El anterior sigue funcionando durante 24 horas y, durante ese tiempo, cada entrega incluye dos firmas, una para cada secreto. Añade el nuevo secreto a tu servidor antes de que transcurran las 24 horas.
Si vuelves a rotar el secreto dentro de las 24 horas, el secreto más antiguo deja de funcionar de inmediato. La rotación solo se puede hacer en la aplicación. La API no puede rotar un secreto.
Entregas y reintentos
Cualquier respuesta 2xx recibida en un plazo de 10 segundos cuenta como entrega. No se siguen las redirecciones.
Una entrega fallida se reintenta 5 veces: al cabo de 30 segundos, 5 minutos, 30 minutos, 2 horas y 12 horas.
Las entregas pueden llegar desordenadas y, ocasionalmente, más de una vez.
Después de 50 intentos fallidos consecutivos, el endpoint se desactiva. Vuelve a activarlo en la aplicación o con
PATCH /webhooks/:idy"enabled": true.Las URL de los endpoints deben usar HTTPS y resolver a una dirección pública.
Gestiona endpoints con la API
curl -X POST https://api.ferndesk.com/v1/webhooks \
-H "Authorization: Bearer $FERNDESK_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webhooks/ferndesk", "events": ["article.published", "article.deleted"]}'Solicitud | Qué hace |
|---|---|
| Crea un endpoint a partir de |
| Muestra los endpoints, del más reciente al más antiguo. |
| Un endpoint y sus últimas 20 entregas. |
| Cambia |
| Elimina el endpoint. Las entregas se detienen y el secreto deja de funcionar. |
| Envía un evento |
| Una entrega, con su estado, código de respuesta e intentos. |
En la aplicación, el menú de un endpoint incluye Enviar evento de prueba y Ver entregas. Las claves y los alcances se encuentran en Autenticación.