Webhook

Cómo funciona un webhook

1. Registro. Das al sistema de origen una URL de endpoint y la lista de eventos que quieres recibir.
2. Evento. Ocurre algo en el sistema de origen.
3. Entrega. El origen envía una solicitud POST a tu URL con un cuerpo JSON y un encabezado de firma.
4. Confirmación. Tu receptor comprueba la firma y responde con un estado 2xx en pocos segundos. El trabajo lento se hace después, en una cola.
5. Reintento. Si la respuesta no es 2xx, o no llega ninguna, el origen vuelve a intentarlo con retrasos crecientes. Tras varios fallos suele desactivar el endpoint.

Parte	Qué es
URL del endpoint	La dirección de tu lado que recibe las entregas
Tipo de evento	Un nombre como asset.updated que indica qué ocurrió
Payload	El cuerpo JSON: el evento, una marca de tiempo y los identificadores
Secreto	Una clave compartida que sirve para firmar y verificar cada entrega
Registro de entregas	El registro de intentos, códigos de respuesta y errores

Webhook vs polling de una API

	Polling de una API	Webhook
Quién inicia la solicitud	Tu sistema, según un calendario	El sistema de origen, cuando ocurre el evento
Retraso	Hasta un intervalo de polling	Normalmente segundos
Carga	Muchas solicitudes que no devuelven nada nuevo	Una solicitud por evento
Ideal para	Conciliación masiva, informes	Reaccionar a cambios individuales

Los dos funcionan juntos. Un webhook te avisa de que algo cambió, y la API te da los detalles. Muchos sistemas envían solo identificadores en el payload, de modo que el receptor lee el estado actual desde la API en lugar de fiarse de una copia que puede estar ya desactualizada.

Cómo proteger los webhooks

• Verifica la firma. La mayoría de los proveedores firman cada entrega con HMAC (RFC 2104, IETF, 1997) usando SHA-256 y el secreto compartido. Calcula el mismo valor sobre el cuerpo sin procesar y compara ambos en tiempo constante.
• Comprueba la marca de tiempo. Rechaza las entregas firmadas hace más de unos minutos, para que una solicitud capturada no pueda reproducirse más tarde.
• Usa HTTPS para el endpoint.
• Haz que el manejador sea idempotente. Los reintentos implican que el mismo evento puede llegar dos veces. Procesarlo por segunda vez no debe crear un segundo registro.
• Rota el secreto cuando se va alguien con acceso o se sospecha una filtración.
• Del lado del emisor, rechaza las direcciones privadas. Un sistema que entrega a cualquier URL puede ser dirigido a servicios internos (server-side request forgery), así que un emisor prudente solo entrega a hosts de internet pública.

Webhooks en el trabajo de un DAM y de marketing

• Sitio web y CMS. Cuando se actualiza una foto de producto aprobada, el receptor del equipo web vacía la caché de la CDN para que las páginas de producto muestren el archivo nuevo.
• Información de producto. Cuando un nuevo packshot termina la ingesta, un receptor lo asocia al SKU correcto en el sistema de información de producto.
• Aprobación. Cuando un recurso llega a «Aprobado» en un flujo de trabajo, un receptor publica en el canal de chat del equipo o inicia una tarea de traducción.
• Actividad de los socios. Cuando un distribuidor abre un enlace para compartir o descarga desde él, el CRM registra la actividad en la cuenta para el equipo de ventas.
• Importaciones de agencias. Cuando termina un lote importado por una agencia, se inicia una comprobación de calidad.

Errores habituales: hacer trabajo lento antes de responder, lo que provoca tiempos de espera agotados, reintentos y duplicados; analizar el JSON antes de verificar la firma, lo que cambia los bytes que cubre la firma; y no darse cuenta de que el emisor ha desactivado un endpoint tras varios fallos.

Webhooks en Freedam

• Los endpoints se registran a través de la API REST con un token que tenga la capacidad Gestionar webhooks. Los eventos cubren recursos (creados, actualizados, eliminados, descargados), colecciones y los recursos que se añaden o se quitan de ellas, enlaces para compartir (creados, abiertos o descargados desde ellos), lotes importados (completados o fallidos) y cambios de estado de flujos de trabajo, o * para todos.
• Cada entrega es un POST firmado: un HMAC-SHA256 de la marca de tiempo y del cuerpo sin procesar, enviado en los encabezados X-Freedam-Signature-256 y X-Freedam-Timestamp. El SDK de TypeScript incluye una función de verificación. El secreto se muestra una sola vez y se puede rotar.
• Tu receptor tiene 30 segundos para responder. Una entrega fallida se reintenta hasta 5 veces, tras 10 segundos, 1 minuto, 5 minutos y 30 minutos. Tras 10 intentos fallidos seguidos, el endpoint se desactiva.
• Un endpoint solo recibe eventos sobre los elementos que su propietario podría ver a través de la API, de modo que un webhook no puede revelar recursos ocultos por el control de acceso.
• Las entregas solo van a hosts de internet pública. La URL se comprueba cuando se guarda el endpoint y de nuevo en cada entrega, después de resolver el nombre del host.
• Los administradores ven todos los endpoints en la pestaña Webhooks de la página Gestión de API, con un gráfico del estado de los webhooks, y pueden desactivar, volver a activar o eliminar un endpoint, o restablecer su contador de fallos.

Detalles: la página para desarrolladores de webhooks y la referencia de webhooks en la documentación de Freedam.

Preguntas frecuentes

¿Cuál es la diferencia entre un webhook y una API?

Una API responde a las solicitudes que envía tu sistema. Un webhook es una solicitud que el otro sistema te envía a ti cuando ocurre algo. Las integraciones suelen usar ambos: el webhook anuncia el cambio, y una llamada a la API obtiene los datos actuales.

¿Qué es una URL de webhook?

Es la dirección del receptor que gestionas tú, por ejemplo una ruta de tu propia aplicación o de una herramienta de automatización. El sistema de origen envía allí sus entregas. Debe ser accesible desde internet y solo debe aceptar solicitudes con una firma válida.

¿Qué pasa si mi endpoint de webhook no funciona?

El emisor reintenta durante un tiempo y después suele desactivar el endpoint. Los eventos que ocurren mientras está desactivado a menudo no se ponen en cola, así que, tras una caída, compara tus datos con el origen a través de su API para detectar lo que te perdiste.