> For the complete documentation index, see [llms.txt](https://docs.barte.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.barte.com/guias/webhooks/assinatura-de-webhook.md).

# Assinatura de Webhook (HMAC-SHA256)

Valide a autenticidade e integridade das notificações recebidas da Barte usando HMAC-SHA256.

## O que é e por que usar

A Barte já opera com **IP de saída fixo** nas entregas de webhook, permitindo que você configure um allowlist de IPs no firewall como primeira camada de verificação.

A assinatura de webhook é uma camada **complementar**, que opera no nível da aplicação e resolve dois problemas que o IP fixo não endereça:

* **Integridade do payload:** garante que o conteúdo da notificação não foi alterado em trânsito.
* **Autenticidade verificável em qualquer ambiente:** funciona em ambientes serverless e sem controle de firewall.

{% hint style="info" %}
A assinatura de webhook é **opcional e retrocompatível**. Quem não configurar um secret continua recebendo webhooks normalmente, sem nenhuma quebra.
{% endhint %}

***

## Como funciona

Quando você configura um `secret` no webhook, a Barte passa a:

1. Montar um **payload canônico** concatenando timestamp, nonce e corpo da requisição.
2. Calcular `HMAC-SHA256(secret, payload_canônico)` antes de cada entrega.
3. Incluir o resultado no header `X-Webhook-Signature: sha256=<hex>`.

Do seu lado, você monta o mesmo payload canônico, recalcula o HMAC com o seu secret e compara com o header recebido. Se baterem, a notificação é autêntica e o payload não foi alterado.

### Payload canônico

```
{timestamp}.{nonce}.{body}
```

| Campo       | Origem                                                 |
| ----------- | ------------------------------------------------------ |
| `timestamp` | Valor exato do header `X-Webhook-Timestamp`            |
| `nonce`     | Valor exato do header `X-Webhook-Nonce`                |
| `body`      | Corpo bruto da requisição (raw JSON, sem reformatação) |

Os três campos são concatenados com `.` como separador.

### Algoritmo

```
signature = "sha256=" + hex(HMAC_SHA256(secret, "{timestamp}.{nonce}.{body}"))
```

A assinatura é sempre em **hexadecimal minúsculo**, prefixada com `sha256=`.

> O nonce e o timestamp são incluídos na assinatura para mitigar **replay attacks** — um payload interceptado não pode ser reusado porque o timestamp estará fora da janela de tolerância.

***

## Novos headers

Quando a assinatura está habilitada, a Barte inclui três novos headers na entrega:

| Header                | Exemplo                                                                   | Descrição                                                             |
| --------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `X-Webhook-Timestamp` | `1789046804`                                                              | Unix timestamp (segundos) do momento da entrega                       |
| `X-Webhook-Nonce`     | `228bb8a88c43c8655145ea2aaaf2ae60`                                        | Valor aleatório único por entrega, usado para prevenir replay attacks |
| `X-Webhook-Signature` | `sha256=a28acabd32c79bdcb219dfd50396d97df4b1119e8c0b4fcd671f13b0ae118ac7` | Assinatura HMAC-SHA256 do payload canônico                            |

***

## Como configurar o secret

O secret é definido **apenas no momento da criação** do webhook. Não é possível gerar ou visualizar o secret em edições posteriores.

1. Acesse o painel da Barte e vá em **Configurações → Integração**.
2. Clique em **Novo Webhook**.
3. No campo de secret, escolha uma das opções:
   * **Geração automática:** ative o toggle de geração automática e a Barte criará um secret seguro para você.
   * **Secret próprio:** informe um valor de sua escolha com **entre 32 e 64 caracteres**.
4. Clique em **Salvar** e copie o secret exibido.

{% hint style="warning" %}
**O secret é exibido apenas uma vez, no momento da criação.** Salve-o imediatamente em um local seguro — não será possível recuperá-lo depois. Se perder o secret, será necessário cadastrar um novo webhook para obter um novo valor.
{% endhint %}

***

## Como verificar a assinatura

Ao receber uma notificação, siga os passos:

1. Leia os headers `X-Webhook-Timestamp`, `X-Webhook-Nonce` e `X-Webhook-Signature`.
2. Capture o **corpo bruto** da requisição — sem fazer parse nem reserializar o JSON. Qualquer alteração de espaços ou ordem de chaves invalida a assinatura.
3. Monte a string `"{timestamp}.{nonce}.{body}"` e calcule o HMAC-SHA256 com o seu secret.
4. Compare o resultado com `X-Webhook-Signature` usando **comparação em tempo constante**.
5. **Recomendado:** valide que o `X-Webhook-Timestamp` está dentro de uma janela de tolerância (ex.: ±5 minutos) para mitigar replay attacks. Opcionalmente, controle os nonces já processados para rejeitar reenvios idênticos.

{% hint style="danger" %}
**Sempre use comparação em tempo constante** — `hmac.compare_digest` no Python, `crypto.timingSafeEqual` no Node.js, `hash_equals` no PHP, `MessageDigest.isEqual` no Java. Comparação simples com `==` é vulnerável a timing attacks.
{% endhint %}

***

## Como rotacionar o secret

Caso precise trocar o secret de um webhook (por exemplo, se o valor anterior foi comprometido), siga o fluxo abaixo:

1. **Cadastre um segundo webhook** com a mesma URL e o secret novo.
2. **Atualize seu sistema** para aceitar assinaturas geradas com o secret novo.
3. **Valide** que as entregas estão chegando e sendo verificadas corretamente.
4. **Delete o webhook antigo** após confirmar que tudo está funcionando.

{% hint style="warning" %}
Não exclua o webhook antigo antes de validar o novo — você pode perder entregas durante a transição.
{% endhint %}

***

## Perguntas frequentes

**Preciso implementar o signing?** Não. É opcional. Se você não configurar um secret, os webhooks continuam sendo entregues normalmente, sem o header `X-Webhook-Signature`.

**O que acontece se eu não verificar a assinatura?** Os eventos são entregues normalmente. A verificação é uma proteção do seu lado — sem ela, seu sistema não tem como distinguir uma notificação legítima da Barte de uma requisição forjada.

**Como testar em sandbox?** Configure um webhook no ambiente de sandbox com qualquer secret de sua escolha e dispare um evento de teste. Verifique se o header `X-Webhook-Signature` chega e se o HMAC calculado bate com o valor recebido.

**O secret aparece em algum endpoint GET?** Parcialmente. A API retorna um preview com os **5 primeiros caracteres** do secret, permitindo identificar qual valor foi configurado. O secret completo nunca é retornado após a criação.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.barte.com/guias/webhooks/assinatura-de-webhook.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.