> ## Documentation Index
> Fetch the complete documentation index at: https://docs.teceo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# boas práticas

> como implementar webhooks de forma robusta

## responda rápido

nunca processe tudo dentro da requisição. responda `2XX` imediatamente e processe em background.

<Tip>o timeout por tentativa é de 10 segundos. para processamentos mais lentos, use filas (SQS, RabbitMQ, etc).</Tip>

## trate idempotência

retries automáticos podem entregar o mesmo evento mais de uma vez. use `eventId` como chave única para evitar processamento duplicado.

```javascript theme={null}
const exists = await db.webhookEvents.findOne({ eventId });
if (exists) return res.status(200).json({ ok: true }); // já processou

await processEvent(data);
await db.webhookEvents.create({ eventId, processedAt: new Date() });
```

## valide a assinatura

configure um signing secret e valide cada requisição. sem validação, qualquer um pode enviar POSTs para sua URL.

veja como implementar em [assinando requisições](./assinando-requisicoes).

## retorne o código HTTP correto

| situação                                    | retorne | resultado                                     |
| ------------------------------------------- | ------- | --------------------------------------------- |
| sucesso                                     | `2XX`   | marcamos como entregue                        |
| erro temporário (banco fora, rede instável) | `5XX`   | tentamos de novo                              |
| erro permanente (dados inválidos)           | `4XX`   | marcamos como falho, sem retry (exceto `429`) |

<Warning>nunca retorne `200` para esconder um erro — isso faz o evento sumir silenciosamente.</Warning>

## registre logs

guarde logs de cada webhook recebido: `eventId`, `eventType`, timestamp e resultado do processamento. quando algo der errado, os logs são o único ponto de diagnóstico.

## monitore

acompanhe taxa de sucesso e eventos com falha no painel em **integrações > webhooks**. veja [monitoramento](./monitoramento).