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

# Verificação de Assinatura em Webhook e Idempotência

Webhooks notificam um backend parceiro sobre mudanças assíncronas no estado do negócio. Como a entrega pode ser tentada novamente, todo receptor deve verificar a assinatura antes de analisar dados confiáveis e deve processar o evento de forma idempotente.

<h2 id="webhook-headers">
  Cabeçalhos Webhook
</h2>

| Cabeçalho          | Descrição                                   |
| ------------------ | ------------------------------------------- |
| X-Agente-Timestamp | Carimbo de data e hora do Unix em segundos. |
| X-Agente-Nonce     | Proteção contra repetição.                  |
| X-Agent-Signature  | HMAC-SHA256 assinatura.                     |

```text
timestamp + nonce + rawBody
```

Use o corpo bruto exato da solicitação recebido sobre HTTP ao reconstruir o valor assinado. Analisar e reserializar JSON primeiro pode alterar a ordem dos espaços em branco ou dos campos e produzir uma assinatura diferente.

<h2 id="verification-flow">
  Fluxo de verificação
</h2>

1. Leia os cabeçalhos de carimbo de data/hora, nonce e assinatura.
2. Capturar o corpo bruto da solicitação não modificado.
3. Construa `timestamp + nonce + rawBody`.
4. Calcule HMAC-SHA256 com o parceiro API segredo.
5. Compare as assinaturas calculadas e recebidas usando uma comparação em tempo constante.
6. Aplique as verificações aprovadas de atualização e reutilização de data.
7. Analisar e processar o evento somente após o sucesso da verificação.

Quando um verificador oficial de Agent SDK estiver disponível, use-o em vez de manter um código de assinatura independente.

<h2 id="order-idempotency">
  Idempotência de ordem
</h2>

| Caso                            | Dirigibilidade                                            |
| ------------------------------- | --------------------------------------------------------- |
| Pedido inicial de transferência | Crie uma agentOrderNoglobalmente única.                   |
| HTTP tempo                      | Consulte a agentOrderNo original antes de criar uma nova. |
| PROCESSING resposta             | Espere pelo status do webhook ou da ordem de consulta.    |
| Webhook repetido                | Deduplicar pela chave de idempotência e status final.     |

<h2 id="recommended-idempotency-record">
  Registro recomendado de idempotência
</h2>

Armazene informações suficientes para reconhecer uma entrega repetida e recuperar com segurança:

| Campo                         | Propósito                                                                |
| ----------------------------- | ------------------------------------------------------------------------ |
| Chave de evento ou negócio    | Identifica de forma única a notificação ou operação.                     |
| Número do pedido do parceiro  | Conecta o evento ao pedido original.                                     |
| Hash da carga útil            | Ajuda a identificar cargas úteis repetidas e conflitantes.               |
| Estado atual de processamento | Distingue trabalhos recebidos, processando, bem-sucedidos e fracassados. |
| Status final do negócio       | Impede que uma ação terminal seja aplicada duas vezes.                   |
| Carimbo de data processado    | Apoia políticas de investigação e retenção.                              |

Comprometa o registro de mudança de negócio e de idempotência na mesma transação sempre que possível. Um evento repetido deve devolver o resultado já conhecido em vez de aplicar novamente o saldo, ordem ou alteração do usuário.

<h2 id="timeout-and-retry-rule">
  Regra do tempo limite e da tentativa de retentar
</h2>

Um tempo de espera HTTP não prova que a solicitação original falhou. Consulte a operação usando o `agentOrderNo`original ou espere pelo webhook antes de decidir se outra ação é necessária. Criar um novo número de ordem de negócio após cada timeout pode causar movimentos duplicados de fundos.

<h2 id="production-checklist">
  Checklist de produção
</h2>

* Verificar a assinatura antes de JSON análise ou processamento empresarial.
* Preservar o corpo bruto independentemente da carga útil analisada.
* Rejeitar solicitações obsoletas ou reproduzidas de acordo com a política de integração aprovada.
* Tornar o processamento de eventos seguro para entregas repetidas e fora de ordem.
* Registrar IDs de eventos, números de pedido de parceiros, resultado de processamento e tempo de solicitação.
* Redigir segredos e valores de assinatura de logs e anexos de suporte.

<h2 id="related-docs">
  Documentação relacionada
</h2>

#### [Segredos e HMAC Assinatura](/pt-BR/sdk/security/secrets-signing)

Proteja o segredo API usado para verificação de solicitações e webhooks.

#### [Agent SDK Visão Geral](/pt-BR/sdk/agent-sdk/overview)

Revise o fluxo completo de integração do backend.

#### [SDK Solução de problemas](/pt-BR/sdk/security/troubleshooting)

Investigue assinaturas rejeitadas, eventos repetidos e operações pendentes.