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

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

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

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

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

1. Lee los encabezados de la marca de tiempo, nonce y signature.
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 usando una comparación en tiempo constante.
6. Aplicar las verificaciones aprobadas de frescura y reutilización con marca de tiempo.
7. 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.

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

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

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

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.

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

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

<h2 id="related-docs">
  Documentos relacionados
</h2>

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

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

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

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

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

Investigar firmas rechazadas, eventos repetidos y operaciones pendientes.