¿Qué es un webhook? La diferencia entre API y webhooks

Un webhook envía automáticamente una notificación HTTP a otro sistema cuando ocurre un evento, como un pago completado o un nuevo pedido.

Este modelo puede ser más rápido y eficiente que consultar repetidamente la API para detectar cambios.

¿Cómo funciona un webhook?

El receptor proporciona una URL de callback. El origen envía los datos cuando ocurre el evento.

Diferencia con las consultas periódicas a la API

En consultas periódicas, el cliente pregunta si ha habido cambios. Con webhooks, el sistema de origen notifica al cliente cuando ocurre un cambio.

Carga útil de Webhook

La carga útil puede incluir tipo de evento, ID de recurso, marca de tiempo y datos relacionados. También es habitual enviar el ID y obtener detalles mediante la API.

Verificación de firma

Como el endpoint webhook es accesible desde Internet, verifique que las solicitudes proceden del proveedor esperado. Las firmas HMAC son un método habitual.

Mecanismo de reintentos

Si el receptor no está disponible temporalmente, el origen puede reenviar el webhook. Documente el número de reintentos y la estrategia de backoff.

Eventos duplicados

El mismo webhook puede venir más de una vez. El procesamiento duplicado debe evitarse usando el ID de evento o la clave de negocio.

Utilizar colas

El endpoint puede validar la carga y ponerla en cola en vez de ejecutar tareas pesadas durante la solicitud. Así puede confirmar pronto la recepción.

Monitoreo de Webhook

Número de eventos fallidos
Número de reintentos
Latencia de procesamiento
Evento duplicado
Fallo en la verificación de firma
Tareas pendientes en la cola

Lista de comprobación de integraciones en producción

En producción, incorpore al modelo operativo estos elementos: el funcionamiento de webhooks, diferencias con consultas periódicas y cargas útiles. Defina origen, destino, responsable de datos, autenticación, tabla de mapeo y responsable de fallos de cada integración. Un endpoint funcional no implica éxito si actualiza el producto, cliente o pedido equivocados.

Prevea en producción tiempos de espera agotados, límites de frecuencia, fallos temporales de red, solicitudes duplicadas y respuestas inesperadas. Reintente solo fallos temporales y use idempotencia cuando repetir una operación pueda tener efectos financieros u operativos. Las colas desacoplan las solicitudes del usuario del rendimiento externo y permiten reprocesar tareas fallidas de forma controlada.

Supervise los resultados de negocio además de los códigos HTTP. Una API puede devolver HTTP 200 sin que llegue ningún pedido al ERP. Muestre solicitudes, tasa de error, latencia P95, reintentos, tareas en cola y última sincronización correcta junto con los volúmenes de pedidos, existencias o clientes transferidos. Los ID de correlación y registros estructurados ayudan a seguir una operación entre servicios durante un incidente.

Autenticación y gestión de secretos
Mapeo de datos y validación de esquemas
Política de tiempos de espera y reintentos
Idempotencia y control de duplicados
Gestión de límites de frecuencia de solicitudes
Registros estructurados e ID de correlación
Conciliación de datos de negocio
Alerta y tablero de control

Contrato de API, modo de fallo y coherencia de datos

No diseñe solo el flujo de solicitud-respuesta correcto. Defina un contrato API claro para el funcionamiento de webhooks, diferencias con consultas periódicas y cargas útiles, con campos obligatorios, tipos, valores enum, autenticación, tiempos de espera, códigos de error y cambios incompatibles. Determine qué respuestas requieren reintento, interrupción o intervención humana para hacer el comportamiento más predecible.

Además de la caída total del servicio, prevea respuestas lentas, datos parciales, eventos duplicados o fuera de orden, límites de frecuencia y fallos temporales de autenticación. Los reintentos pueden usar backoff exponencial y, cuando proceda, jitter. La idempotencia o claves de negocio únicas reducen duplicados al reprocesar pedidos, pagos, existencias o clientes.

Una respuesta API correcta no basta para confirmar la coherencia de los datos. Concilie origen y destino por número de registros, importe total, última sincronización o ID de negocio para detectar diferencias. Los registros estructurados, ID de correlación y seguimiento central de errores ayudan a localizar el servicio que falla. Así, la conexión se convierte en un componente operativo auditable y sostenible.

Validación de esquemas de solicitud y respuesta
Matriz de tiempos de espera y reintentos
Idempotencia o claves de negocio únicas
Límites de frecuencia y gestión de capacidad
ID de correlación y registros estructurados
Comprobaciones de conciliación entre origen y destino
Política de versiones y cambios incompatibles

El enfoque de integración de B10 Digital Agency

B10 Digital Agency trata la integración como arquitectura de sistemas, no solo una conexión API: contratos de datos, seguridad, reintentos, colas, observabilidad, conciliación y operaciones se diseñan conjuntamente.

Preguntas frecuentes

¿Es Webhook en tiempo real?

La entrega suele ser cercana al evento, pero retrasos de red y reintentos pueden impedir una garantía absoluta de tiempo real.

¿Necesitas una API para Webhook?

No siempre. En muchas arquitecturas se usa una API con webhooks para obtener detalles después del evento.

¿Cómo hacer Webhook seguro?

Use TLS, verificación de firma, comprobación de marcas de tiempo y autorización adecuada.

¿Puede Webhook venir dos veces?

Sí. El sistema receptor debe, por ello, procesar de forma idempotente.

Combine sus sistemas con un flujo de datos confiable

Conozca las integraciones API y sistemas de B10 Digital Agency para planificar la arquitectura de ERP, CRM, marketplaces, software a medida y servicios de terceros.

Conocer las integraciones API y sistemas →