Verificación e Idempotencia de la Firma de Webhook

Los Webhooks notifican a un backend asociado 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 idempotentemente.

Encabezados de Webhook

Encabezado	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

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

Flujo de verificación

Lee los encabezados de la marca de tiempo, nonce y signature.
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 usando una comparación en tiempo constante.
Aplicar las verificaciones aprobadas de frescura y reutilización con marca de tiempo.
Analizar y procesar el evento solo después de que la verificación tenga éxito.

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

Idempotencia de orden

Caso	Manejo
Solicitud inicial de transferencia	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.

Registro recomendado de idempotencia

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

Campo	Propósito
Clave de evento o negocio	Identifica de manera única la notificación u operación.
Número de orden de 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 del negocio	Evita que una acción terminal se aplique dos veces.
Marca de tiempo 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 nuevamente el saldo, orden o cambio de usuario.

Regla de tiempo fuera y reintento

Un tiempo de espera HTTP no prueba que la solicitud 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 después de cada tiempo de espera puede causar 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 repetidas 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 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 firmas HMAC

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

Agent SDK Resumen

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

SDK Solución de problemas