> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.6mm.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.6mm.com/_mcp/server.

# 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.

<h2 id="webhook-headers">
  Encabezados de webhook
</h2>

| 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.                   |

```text
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.

<h2 id="verification-flow">
  Flujo de verificación
</h2>

1. Lee los encabezados de la marca de tiempo, nonce y de la firma.
2. Capturar el cuerpo de la solicitud sin modificar.
3. Construye `timestamp + nonce + rawBody`.
4. Calcular HMAC-SHA256 con el compañero API secreto.
5. Comparar las firmas calculadas y recibidas mediante una comparación en tiempo constante.
6. Aplicar los controles aprobados de fecha y reutilización de la hora.
7. 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.

<h2 id="order-idempotency">
  Idempotencia de orden
</h2>

| 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.        |

<h2 id="recommended-idempotency-record">
  Historial recomendado de idempotencia
</h2>

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.

<h2 id="timeout-and-retry-rule">
  Regla de tiempo muerto y reintento
</h2>

Un tiempo de espera HTTP no demuestra que la petición original falló. Consulta la operación usando el `agentOrderNo`original 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.

<h2 id="production-checklist">
  Lista de verificación de producción
</h2>

* 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.

<h2 id="related-docs">
  Documentación relacionada
</h2>

#### [Secretos y HMAC firmas](/es-ES/sdk/security/secrets-signing)

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

#### [Agent SDK Resumen](/es-ES/sdk/agent-sdk/overview)

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

#### [SDK Resolución de problemas](/es-ES/sdk/security/troubleshooting)

Investigar firmas rechazadas, eventos repetidos y operaciones pendientes.