Verificación de firma en Webhook e Idempotencia

Los Webhooks notifican a un backend socio sobre cambios asíncronos en el estado del negocio. Como la entrega puede intentarse de nuevo, cada receptor debe verificar la firma antes de analizar datos confiables y debe procesar el evento de forma idempotente.

Encabezados de webhook

Cabecera	Descripción
X-Agent-Timestamp	Marca de tiempo de Unix en segundos.
X-Agente-Nonce	Protección contra repeticiones.
X-Agent-Signature	HMAC-SHA256 firma.

timestamp + nonce + rawBody

Utiliza el cuerpo exacto de la solicitud en bruto recibido sobre HTTP al reconstruir el valor con firma. Analizar y volver a serializar JSON primero puede cambiar el orden del espacio en blanco o de los campos y producir una firma diferente.

Flujo de verificación

Lee los encabezados de la marca de tiempo, nonce y de la firma.
Capturar el cuerpo de la solicitud sin modificar.
Construye timestamp + nonce + rawBody.
Calcular HMAC-SHA256 con el compañero API secreto.
Comparar las firmas calculadas y recibidas mediante una comparación en tiempo constante.
Aplicar los controles aprobados de fecha y reutilización de la hora.
Analizar y procesar el evento solo después de que la verificación tenga éxito.

Cuando haya disponible un verificador oficial de Agent SDK , úsalo en lugar de mantener un código de firma independiente.

Idempotencia de orden

Caso	Manejo
Solicitud inicial de traspaso	Crea una agentOrderNoúnica a nivel mundial.
HTTP tiempo fuera	Consulta el agentOrderNo original antes de crear uno nuevo.
PROCESSING respuesta	Espera el estado del webhook o de la consulta de la orden.
Webhook repetido	Deduplicar por clave de idempotencia y estado final.

Historial recomendado de idempotencia

Guarda suficiente información para reconocer una entrega repetida y recuperarla de forma segura:

Campo	Propósito
Clave de evento o negocio	Identifica de forma única la notificación u operación.
Número de pedido del socio	Conecta el evento con la solicitud original.
Hash de carga útil	Ayuda a identificar cargas útiles repetidas en conflicto.
Estado actual de procesamiento	Distingue trabajos recibidos, procesando, exitosos y fallidos.
Estado final de la empresa	Evita que una acción terminal se aplique dos veces.
Marca temporal procesada	Apoya políticas de investigación y retención.

Compromete el registro de cambio de negocio e idempotencia en la misma transacción cuando sea posible. Un evento repetido debería devolver el resultado ya conocido en lugar de aplicar de nuevo el saldo, pedido o cambio de usuario.

Regla de tiempo muerto y reintento

Un tiempo de espera HTTP no demuestra que la petición original falló. Consulta la operación usando el agentOrderNooriginal o espera su webhook antes de decidir si se requiere otra acción. Crear un nuevo número de orden de negocio tras cada tiempo de espera puede provocar movimientos duplicados de fondos.

Lista de verificación de producción

Verificar la firma antes de JSON análisis o procesamiento empresarial.
Preservar el cuerpo bruto independientemente de la carga útil analizada.
Rechazar solicitudes obsoletas o reproducidas según la política de integración aprobada.
Hacer que el procesamiento de eventos sea seguro para entregas repetidas y fuera de orden.
Registrar los IDs de eventos, números de pedido de socios, resultados de procesamiento y tiempo de solicitud.
Redactar secretos y valores de firma de registros y adjuntos de soporte.

Secretos y HMAC firmas

Protege el API secreto utilizado para la verificación de solicitudes y webhooks.

Agent SDK Resumen

Revisa todo el flujo de trabajo de integración del backend.

SDK Resolución de problemas