BlogEventos de integración
Webhooks que fallan: reintentos sin duplicar trabajo ni perder eventos
Que el proveedor recibió un «200» no significa que tu operación se actualizó. Separa recepción, procesamiento y comprobación del resultado.
Hoja de prueba: Webhooks: reintentos y aceptación sin duplicados
Que el proveedor recibió un «200» no significa que tu operación se actualizó. Separa recepción, procesamiento y comprobación del resultado. Registra datos, resultado esperado, evidencia, responsable y resultado observado.
Define qué significa cada confirmación
Un webhook es un aviso que un sistema envía a otro cuando ocurre algo. En una transportista puede informar que una entrega terminó; en servicios, que un archivo de evidencia está disponible. La confirmación técnica de recepción y la aceptación del negocio son estados distintos. Decide dónde consultar cada uno y quién resolverá un evento que quedó pendiente.
Stripe documenta validación de firma y respuesta exitosa rápida antes de lógica compleja. Shopify publica condiciones de reintento y seguimiento de entregas fallidas. Son contratos de proveedores concretos, no una regla universal para todas las conexiones. Confirma el plazo, autenticación e identificadores que utiliza tu proveedor antes de diseñar la recepción.
Ejemplo ficticio: aviso de entrega EV-72
El sistema de rutas envía EV-72 para la entrega E-017. El receptor comprueba su autenticidad, conserva el evento de forma durable y devuelve recepción correcta. La actualización de E-017 queda pendiente porque falta un documento. El proveedor repite EV-72 al no haber recibido la primera respuesta. Este es un ejemplo sintético de eventos operativos, no de un cobro ni de una integración ya implementada.
El resultado esperado es un evento recibido con dos intentos de entrega, y ninguna segunda operación por el reintento. Cuando el documento está disponible, un responsable o proceso autorizado retoma el trabajo y marca E-017 actualizada. El historial conserva recepción y aplicación por separado. Si el evento nunca se guardó, responder éxito habría ocultado una pérdida; ese caso debe fallar el ensayo.
| Estado | Qué demuestra | Qué falta |
|---|---|---|
| Recibido | Aviso autenticado y conservado | Aplicar o decidir el trabajo |
| Pendiente | Evento localizable con causa | Resolver dependencia y reintentar |
| Aplicado | Resultado de negocio comprobable | Conciliación cuando corresponda |
| Rechazado | No se aplicó por motivo explícito | Corrección autorizada o cierre |
Ensaya fallos en cada frontera
Usa un ambiente de prueba y un origen autorizado. Prueba antes y después de guardar el evento, antes y después de aplicar el cambio, y al perder la respuesta. El mismo identificador de evento sirve para reconocer su reenvío, pero puede no bastar para reconocer dos avisos distintos sobre la misma operación. Acuerda también la clave de la operación que no debe repetirse.
| Caso | Resultado esperado | Evidencia |
|---|---|---|
| EV-72 auténtico y completo | Recepción durable y un trabajo identificable | Evento y tarea relacionada |
| EV-72 llega dos veces | Un trabajo de negocio, dos intentos visibles | Clave de evento e intentos |
| Respuesta se pierde después de aplicar | Reintento encuentra el resultado existente | Referencia de operación |
| Documento de E-017 falta | Pendiente con causa; no declarar aplicado | Estado y dependencia |
| Aviso anterior llega tarde | No sobrescribe un estado más reciente sin regla | Versiones y decisión |
| Firma o autenticación inválida | Rechazo sin modificar la entrega | Resultado y registro acotado |
El reintento necesita límites y una salida
Define cuántos intentos internos se harán, qué errores admiten reintento y quién atiende los que se agotan. No reintentes indefinidamente una referencia inexistente o un permiso denegado sin corregir su causa. Una cola pendiente debe tener antigüedad y responsable visibles; «se volverá a intentar» no explica cuándo la operación podrá continuar.
Incluye una conciliación: compara los eventos o estados del origen con los aplicados en el destino. Sirve para detectar lo que nunca llegó o quedó fuera de la cola. Su frecuencia y alcance dependen de la API y del acceso del proveedor. No supongas que conservar avisos equivale a recuperar toda su historia, ni que un envío manual evita la regla de repetición.
Acepta una integración con su resultado de negocio
Prueba consulta y reparación por referencia, además de la entrega técnica. En conectar tu ERP sin reemplazarlo se explica la autoridad de cada dato; las reglas de sincronización ayudan cuando hay cambios concurrentes, y la bitácora de cambios permite explicar qué se aplicó.
La hoja descargable contiene diez casos para ajustar al proveedor real. Lleva un aviso anonimizado, sus identificadores y un fallo conocido a una consulta gratuita de automatización de procesos. Podemos revisar dónde se confirma cada etapa y qué prueba demostraría una recuperación sin duplicar trabajo.
Preguntas frecuentes
Significa lo que el contrato del receptor haya definido. Puede confirmar solo recepción. El comprador necesita un estado separado para el resultado de negocio y una forma de consultar pendientes o rechazos. No derives aplicación correcta únicamente de la respuesta HTTP.
Reconoce el reenvío, pero consulta el estado del trabajo original. Si todavía está pendiente, puede necesitar un reintento controlado. Ignorar el aviso sin conservar o recuperar la tarea puede perder el resultado que esperabas.
Define una regla según versión, secuencia o consulta del estado autorizado del origen. No uses automáticamente la hora de recepción como verdad del negocio. La regla depende del proveedor y debe probarse con un aviso anterior que llegue después.
No sustituye la conciliación de pagos. Distinguir un aviso repetido de un segundo cobro real requiere revisar transacciones y órdenes. Este ensayo se enfoca en la entrega y aplicación de eventos operativos de una conexión.
Fuentes
Última actualización: