> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/caf-api-pt-br/connect/webhook/best-practices.md).

# Melhores práticas

Este guia apresenta recomendações para garantir robustez, confiabilidade e segurança ao integrar com webhooks.

## Responda rapidamente

* Retorne um `202 Accepted` `HTTP` código de status em até 2 segundos após receber uma solicitação de webhook
* Use filas de mensagens (como RabbitMQ, SQS ou Kafka) para processar eventos de forma assíncrona
* Mantenha o processamento do endpoint do webhook leve para evitar timeouts
* Considere implementar um processo worker separado para o tratamento de eventos complexos

## Valide a assinatura usando os bytes brutos do corpo

* Sempre verifique a assinatura do webhook antes de processar qualquer evento
* Use o array de bytes bruto do corpo da solicitação sem nenhuma transformação
* Evite parsing automático ou conversões de codificação de caracteres antes da validação
* Armazene o segredo do seu webhook com segurança (use variáveis de ambiente ou um cofre seguro)
* Exemplo de pseudocódigo para validação de assinatura:

  ```
  calculatedSignature = HMAC-SHA256(webhookSecret, rawRequestBody)
  return calculatedSignature == receivedSignature
  ```

## Lide com atrasos e tentativas de nova entrega

* Os eventos podem chegar atrasados devido a problemas de rede ou mecanismos de nova tentativa
* Sempre verifique o timestamp do evento (`time` campo) para determinar a idade do evento
* Implemente lógica para lidar adequadamente com eventos antigos conforme o seu caso de uso
* Considere definir um limite máximo de idade para processar eventos

## Implemente idempotência

* O mesmo evento pode ser recebido várias vezes devido a problemas de rede ou tentativas de nova entrega
* Use o `id` campo como uma chave de idempotência para detectar e ignorar duplicatas
* Armazene os IDs dos eventos processados em um banco de dados persistente com TTL apropriado
* Torne sua lógica de processamento de eventos idempotente (segura para executar várias vezes)

## Monitore e acompanhe falhas

* Implemente logging abrangente para todos os eventos de webhook
* Monitore métricas de entrega, códigos de resposta e tempos de processamento
* Configure alertas para falhas recorrentes ou padrões incomuns
* Mantenha uma fila de erros dedicada para tentativas de processamento de webhook com falha
* Implemente um dashboard para visualizar métricas de saúde do webhook

## Implemente rotinas de reconciliação

* Se sua aplicação ficar indisponível, você pode perder eventos
* Implemente rotinas de polling para buscar eventos perdidos durante períodos de indisponibilidade
* Agende verificações regulares de consistência entre o seu sistema e a nossa API
* Considere implementar uma dead letter queue para eventos que falharem no processamento várias vezes

## Configure a segurança de rede

* Permita os seguintes IPs do serviço de webhook no seu firewall:
  * 34.234.120.59
  * 18.229.212.133
  * 3.218.90.124
  * 44.219.96.170
  * 18.235.54.162
* Certifique-se de que sua configuração de SSL/TLS esteja atualizada
* Considere usar um serviço de proxy de webhook para segurança adicional
* Implemente limitação de taxa nos seus endpoints de webhook para evitar abuso

## Teste sua implementação

* Use nossas ferramentas de teste de webhook para verificar sua integração
* Implemente um ambiente de desenvolvimento que possa receber webhooks de teste
* Crie testes automatizados para verificar sua lógica de tratamento de webhook
* Revise e atualize regularmente sua integração de webhook


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-api/caf-api-pt-br/connect/webhook/best-practices.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.