Skip to main content

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.

​
responda rápido

nunca processe tudo dentro da requisição. responda 2XX imediatamente e processe em background.
o timeout por tentativa é de 10 segundos. para processamentos mais lentos, use filas (SQS, RabbitMQ, etc).

​
trate idempotência

retries automáticos podem entregar o mesmo evento mais de uma vez. use eventId como chave única para evitar processamento duplicado. 
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.

​
retorne o código HTTP correto

situaçãoretorneresultado
sucesso2XXmarcamos como entregue
erro temporário (banco fora, rede instável)5XXtentamos de novo
erro permanente (dados inválidos)4XXmarcamos como falho, sem retry (exceto 429)
nunca retorne 200 para esconder um erro — isso faz o evento sumir silenciosamente.

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