¿Qué es un Webhook? Eventos, Entrega, Seguridad y Diseño

La API de Scraping sin Scrapear puede enviar una solicitud HTTP POST a una URL de webhook configurada cuando una tarea de scraping asincrónica se completa.

¿Qué es un Webhook?

Un webhook es un mecanismo a través del cual un sistema envía una solicitud HTTP a otro sistema después de un evento. La aplicación receptora registra una URL de punto final y a menudo elige tipos de eventos como tarea completada, factura pagada, registro actualizado, implementación finalizada o mensaje entregado. Cuando ocurre el evento, el productor llama a ese punto final con datos y metadatos del evento.

A veces se describe un webhook como una llamada de API inversa. En una interacción de API ordinaria, el consumidor inicia una solicitud para leer o cambiar el estado. Con un webhook, el productor inicia una solicitud para notificar al consumidor. La URL receptora sigue siendo un punto final HTTP, y la implementación debe aplicar prácticas ordinarias de seguridad, validación, disponibilidad y observabilidad de API.

El Especificación de Webhooks Estándar reúne convenciones para una entrega de webhook segura e interoperable. Cubre cargas útiles, metadatos de eventos, firmas y comportamiento operativo, mientras que los proveedores individuales aún definen sus propios tipos de eventos y contratos.

Cómo Funciona un Webhook

1. El consumidor registra un punto final. El registro puede ocurrir en un panel o API y generalmente asocia un secreto con la suscripción.
2. El consumidor selecciona eventos. Suscripciones reducidas disminuyen el tráfico innecesario y la exposición de datos.
3. El productor registra un evento. Una acción de dominio crea un evento inmutable o tarea de entrega con un identificador estable.
4. El productor construye la carga útil. Serializa un tipo de evento, ID de evento, tiempo de ocurrencia, versión del esquema y datos relevantes.
5. El productor firma la entrega. La firma cubre el cuerpo sin procesar y los metadatos de frescura bajo el esquema documentado.
6. El productor envía una solicitud HTTP. POST con un cuerpo JSON es común, pero el contrato determina el método y tipo de medio.
7. El consumidor verifica y lo registra. El punto final comprueba el transporte, la firma, la marca de tiempo, el ID de evento, el esquema y la suscripción antes de aceptar el evento.
8. El consumidor reconoce. Devuelve el estado de éxito documentado después de la aceptación durable y realiza un procesamiento más largo a través de una cola o trabajador.

Ejemplo de Carga Útil de Webhook

Un pequeño sobre de evento puede separar los metadatos de los datos de dominio:

{
  "id": "evt_7f32",
  "type": "task.completed",
  "occurred_at": "2026-08-24T03:10:00Z",
  "version": "1",
  "data": {
    "task_id": "task_b18c",
    "status": "completed"
  }
}

La fecha mostrada es una constante de código ilustrativa en lugar de un sello de publicación. El ID de evento soporta deduplicación, el tipo selecciona el controlador y esquema, el tiempo de ocurrencia describe el evento de dominio, y la versión controla la evolución de la carga útil. El tiempo de entrega pertenece a los metadatos de solicitud cuando el esquema de firma lo usa.

No asumas que un cuerpo de webhook contiene el recurso completo actual. Algunos productores envían una notificación delgada con un ID, después de la cual el consumidor llama a la API para obtener el estado actual autorizado. Otros envían una instantánea completa del evento. El contrato debe indicar si la carga útil representa el evento, el recurso después del evento, o un puntero.

Webhooks vs Sondeo, APIs y WebSockets

Los sistemas importantes a menudo combinan patrones. Un webhook proporciona una notificación rápida, mientras que un proceso de reconciliación programada compara el estado actual de la API con el estado local. El webhook mejora la latencia; la reconciliación detecta brechas o cambios de política sin asumir que un camino de entrega es perfecto.

Cómo funcionan las firmas de webhook

Un diseño de secreto compartido utiliza comúnmente un hash con clave sobre el cuerpo de la solicitud sin procesar más la metadata como un sello temporal de entrega e ID del evento. HMAC es una construcción estándar para la autenticación de mensajes, definida en RFC 2104.Otros proveedores utilizan firmas asimétricas para que los consumidores puedan verificar con una clave pública.

El consumidor debe seguir el algoritmo byte por byte del proveedor. Analiza el encabezado de la firma según su formato versionado, reconstruye exactamente el contenido firmado, calcula el valor esperado y lo compara a través de una función de tiempo constante. Solo después de la verificación debe el código analizar y confiar en la carga JSON.

El middleware del framework puede romper la verificación cuando analiza JSON y lo serializa nuevamente. El espacio en blanco, el orden de las propiedades, la escapatoria y el formato de números pueden cambiar aunque los datos parezcan equivalentes. Captura los bytes del cuerpo sin procesar antes del análisis ordinario del cuerpo y luego pasa los bytes verificados al analizador JSON.

Protección contra repetición e idempotencia

Un viejo webhook válido puede ser reproducido maliciosamente si la firma nunca expira. Por lo tanto, los esquemas de firma incluyen un sello temporal de entrega o otro valor de frescura. El receptor acepta solo una pequeña ventana temporal documentada y debe mantener su reloj sincronizado. La verificación de la marca temporal complementa, en lugar de reemplazar, la deduplicación de ID de eventos.

La idempotencia significa que procesar el mismo evento lógico más de una vez produce el mismo resultado comercial que procesarlo una vez. Almacena el ID de evento estable del productor en una tabla con una restricción de unicidad, idealmente en la misma transacción que aplica el cambio comercial. Marcar un evento como 'visto' antes de la actualización comercial puede perder trabajo si el proceso se detiene entre esas acciones.

Algunas operaciones son naturalmente idempotentes, como establecer el estado de un registro en una versión específica. Otros, como aumentar un saldo o enviar un mensaje, necesitan un registro de idempotencia vinculado al ID de evento. Deduplica por el identificador documentado del productor, no por el hash de la carga, porque dos eventos legítimos pueden tener cuerpos idénticos.

Ordenamiento y versiones de eventos

El orden de entrega puede diferir del orden de ocurrencia porque los eventos pueden viajar a través de diferentes trabajadores, regiones o colas. Una actualización más nueva puede llegar antes que una más antigua. Los consumidores no deberían tratar el orden de llegada como el orden comercial a menos que el productor lo garantice explícitamente para la suscripción.

Incluye una versión de recurso, secuencia o tiempo de ocurrencia del evento con semánticas definidas. Aplica una actualización de estado solo cuando su versión sea más nueva que la versión local. Para eventos que representan acciones inmutables en lugar de instantáneas de estado, preserva las reglas de secuencia de eventos establecidas por el dominio.

La versión del esquema es independiente de la versión del recurso. La versión del esquema describe la forma de la carga; la versión del recurso describe el estado de una entidad particular. Mantener los conceptos distintos evita que un cambio en el formato de carga parezca un registro comercial más nuevo.

Reconocer primero, procesar a través de una cola

Un punto final de webhook debe hacer trabajo limitado: hacer cumplir el tamaño de la solicitud, verificar la firma, validar el sobre, reservar el ID del evento, almacenar o encolar el evento aceptado y devolver la respuesta de éxito documentada. Uniones lentas de base de datos, llamadas a APIs externas, generación de archivos y envío de correos electrónicos pertenecen a trabajadores.

La aceptación durable es importante. Devolver éxito antes de que el evento sea registrado puede perderlo si el proceso se detiene. Esperar cada acción descendente antes de responder hace que el productor mantenga una conexión y puede causar entregas repetidas cuando el punto final supera su plazo de respuesta.

El mensaje en la cola debe contener el evento verificado, el contexto de suscripción y los identificadores de seguimiento seguros. Los secretos utilizados para la verificación de firma no pertenecen a la carga de la cola.

Seguridad en el registro de puntos finales

Si los usuarios pueden registrar URLs de webhook arbitrarias, el productor se convierte en un cliente HTTP actuando según la entrada del usuario. El sistema debe protegerse contra el fraude de solicitud del lado del servidor. La Guía de prevención de SSRF de OWASP describe controles de lista permitida y de capa de red.

Requiere HTTPS para puntos finales públicos, resuelve y valida destinos, bloquea bucles de retorno, locales de enlace, privados, rangos de metadata y servicios internos, y aplica las verificaciones nuevamente después de redireccionamientos y resolución de DNS de acuerdo con la política elegida. Limitar puertos, métodos, bytes de respuesta, tiempo de conexión y comportamiento de redirección.

Verifica la propiedad del punto final durante el registro a través de un desafío o apretón de manos firmado. Trata los cuerpos de respuesta del webhook como no confiables y no expongas detalles de la red interna a través de mensajes de error de entrega.

Casos de uso comunes de Webhook

Observabilidad y Operaciones

Realice un seguimiento del ID de evento, ID de suscripción, tipo de evento, versión de esquema, tiempo recibido, decisión de verificación, estado de reconocimiento, estado de procesamiento y identificadores de correlación seguros. No registre secretos de firma, encabezados de autorización completos o campos de carga útil sensibles.

Mida la latencia de aceptación, el retraso en la cola, la duración del procesamiento, la tasa de duplicados, fallas de firma, esquemas inválidos, marcas de tiempo obsoletas y conflictos de ordenación. Separe la salud de entrega del productor de la salud del procesamiento empresarial del consumidor para que un evento aceptado que falla más tarde no desaparezca en una métrica de éxito genérica.

Proporcione una vista administrativa controlada que pueda buscar por ID de evento y mostrar el historial de entrega redactado. Los equipos de operaciones necesitan suficiente evidencia para diagnosticar un cambio de estado faltante sin exponer las credenciales o el cuerpo sensible completo.

Lista de Verificación del Diseño de Webhook

1. Defina tipos e ID de eventos estables. Documente si las cargas útiles son eventos, instantáneas o punteros.
2. Versione el esquema. Establezca reglas de compatibilidad para nuevos campos opcionales y revisiones de eventos.
3. Firme bytes sin procesar y metadatos de frescura. Publique pasos de verificación exactos y apoye el reemplazo de secretos.
4. Haga cumplir la seguridad del punto final. Verifique la propiedad y bloquee destinos SSRF.
5. Acepte idempotentemente. Utilice un ID de evento único y un registro de deduplicación seguro transaccionalmente.
6. Reconozca después de una aceptación durable. Mueva trabajos más largos a una cola.
7. Espere repetición y reordenación. Utilice versiones de recursos y reconciliación en lugar de suposiciones de orden de llegada.
8. Redacte datos de observabilidad. Mantenga los secretos y los campos de carga útil sensibles fuera de los registros y herramientas de soporte.

Conclusión

Un webhook convierte un evento en una notificación HTTP, proporcionando integraciones actualizaciones de baja latencia sin necesidad de sondeo constante. La llamada HTTP es la parte fácil. Un diseño de producción verifica las firmas de los cuerpos sin procesar, aplica frescura, deduplica por ID de evento, maneja el reordenamiento, reconoce solo después de una aceptación durable, procesa a través de una cola, protege el registro del punto final de SSRF y reconcilia el estado importante. Esos controles convierten una devolución de llamada en un límite de integración confiable.