Un proveedor cambia un pedido y envía un webhook al ERP. El endpoint responde, pero la aplicación cae antes de aplicar la actualización. Después llega el mismo evento y luego un estado más antiguo retrasado. Un controlador que escribe inmediatamente todo contenido recibido puede dejar inconsistente el registro.
Los webhooks son útiles para recibir eventos externos, pero requieren un modelo deliberado de recepción y procesamiento. La aplicación debe establecer quién envió, conservar lo aceptado y decidir cómo se relaciona el evento con el estado actual. Estas responsabilidades siguen siendo del consumidor aunque el proveedor facilite la entrega.
Lee primero el contrato de entrega del proveedor
Documenta tipos de evento, autenticación o firma, tiempos de espera y reintentos. Comprueba garantías de orden, identificadores y posibilidad de recuperar eventos perdidos. No traslades supuestos de un proveedor a otro solo porque ambos utilicen HTTP POST.
La documentación de GitHub sirve como ejemplo concreto: describe validación, respuestas rápidas y procesamiento asíncrono. Sus detalles se aplican a GitHub; las mismas preguntas deben responderse con la documentación oficial del proveedor integrado. Buenas prácticas de webhooks de GitHub.
En un distribuidor hipotético que recibe eventos de preparación de pedidos, registra qué sistema controla el estado de referencia. Decide si la notificación trae todo lo necesario o debe activar una consulta autenticada del registro más reciente. Esto afecta a corrección y recuperación.
Valida la entrega en el límite de entrada
Utiliza HTTPS y el mecanismo documentado del proveedor. En un webhook firmado, conserva la representación exigida por la firma y utiliza la validación recomendada. Reformatear antes puede cambiar los bytes comprobados e invalidar la comparación.
GitHub documenta firmas con secreto y comparación segura respecto al tiempo. Sigue el esquema exacto del proveedor en lugar de inventar una cabecera genérica que parezca segura. Validación de entregas de GitHub.
Aplica límites de tamaño y valida tipo y estructura antes de aceptar. Mantén credenciales y contenido sensible fuera de registros rutinarios. Una firma válida establece propiedades del origen e integridad; aún debes verificar que recurso y operación pertenecen al alcance previsto.
Confirma solo después de conservar el trabajo aceptado
Separa recibir de terminar el procesamiento de negocio. Cuando corresponda la ejecución asíncrona, registra duraderamente el evento o colócalo en una cola fiable antes de comunicar recepción. De lo contrario, una caída puede convertir una confirmación correcta en trabajo perdido.
Guarda contexto suficiente: proveedor, identificador de entrega, tipo, hora y contenido o referencia adecuados. Elige retención y acceso según la información. Un archivo de eventos no debe convertirse en una copia descontrolada de datos de clientes.
Limita el trabajo de entrada para responder a tiempo sin llamadas externas largas en línea. Si no puedes conservar el evento, devuelve el fallo apropiado según el contrato. Evita declarar aceptación solo para que el panel del proveedor parezca saludable.
Gestiona deliberadamente duplicados y orden
Define una clave de idempotencia adecuada al proveedor y significado del evento. Repetir el procesamiento no debe crear otro envío ni una acción irreversible repetida. Persiste el estado para que la protección sobreviva a reinicios y no dependa solo de memoria.
Distingue identidad de entrega y versión del recurso. Varios eventos pueden referirse al mismo pedido y su estado ya ser más reciente que uno retrasado. Utiliza versiones documentadas, horas de significado conocido o una consulta actual para decidir si todavía se aplica.
En el distribuidor, un evento antiguo «empaquetado» no debe sustituir casualmente «enviado» confirmado. Escribe transiciones permitidas y prueba entregas desordenadas. Si falta información de orden, concilia con el registro de referencia en lugar de adivinar.
Haz revisables los fallos y controla la repetición
Registra resultados y distingue fallos temporales de datos inválidos o cambios de contrato no admitidos. Ofrece a operaciones una vista de eventos pendientes con responsable y siguiente paso. Un archivo de registro creciente no es una cola de excepciones utilizable mientras esperan pedidos.
Permite repetir mediante una operación controlada que compruebe efectos anteriores y registre el motivo. Puede ser adecuado después de corregir código, pero debe ser seguro si parte del intento original funcionó. Evita editar contenido guardado a la ligera para forzar éxito.
Prueba firmas inválidas, duplicados, eventos desconocidos, desorden y caída después de aplicar un efecto. Son casos del contrato que importa en incidentes reales, además de demostrar que se puede deserializar un ejemplo.
Concilia más allá del canal de entrega
Acompaña los webhooks de una forma de detectar resultados de negocio ausentes cuando proveedor y proceso lo permitan. Compara registros de origen o recupera cambios desde un punto conocido. Decide cómo comprobar que se ha puesto al día tras una caída o error de suscripción.
Supervisa antigüedad pendiente y discrepancias de estado junto a fallos de entrega. El proveedor puede informar de respuestas HTTP correctas mientras el ERP sigue retrasado. Conecta las señales con procedimientos que expliquen comunicación y resultado del pedido.
Worktechlabs implementa integraciones de eventos externos con entrada verificada, procesamiento duradero y excepciones recuperables. Combina webhooks con gestión de contratos API y mensajería fiable para explicar qué llegó, qué cambió y qué requiere atención.
Fuentes oficiales y lecturas adicionales
- GitHub: buenas prácticas de webhooks — expectativas documentadas de entrega y procesamiento.
- GitHub: validar entregas de webhooks — verificación del esquema de firma específico de GitHub.
