Práticas Recomendadas

Guia de boas práticas para integrar webhooks de forma segura, eficiente e confiável.

Segurança

Use HTTPS

Sempre configure sua URL de webhook com HTTPS para garantir que os dados sejam transmitidos de forma criptografada.

Valide a Secret Key

Se você configurou uma Secret Key, valide-a em cada requisição. A chave é enviada no header X-Webhook-Secret.

Valide os Payloads

Sempre valide os dados recebidos antes de processar:

• Verifique se os campos obrigatórios existem (event, data, webhook_id)
• Valide se o tipo de evento é conhecido
• Trate campos null adequadamente

Desempenho

Responda Rápido

O MeChat aguarda até 30 segundos por uma resposta. Responda imediatamente com status 200 e processe os dados de forma assíncrona.

Use Filas

Para alto volume de webhooks, use filas de processamento. Isso permite responder rapidamente e processar os eventos em segundo plano.

Implemente Retry

Se sua integração falhar ao chamar sistemas externos, implemente retry com backoff exponencial para evitar sobrecarga.

Confiabilidade

Evite Duplicatas

Use o campo webhook_id para detectar e ignorar webhooks duplicados. Armazene os IDs processados no banco de dados.

Monitore e Alerte

Configure alertas para falhas. Se o processamento falhar, retorne status 500 para que o MeChat tente novamente.

Mantenha Logs

Registre todos os webhooks recebidos para debug e auditoria. Inclua o webhook_id, event e timestamp nos logs.

Organização

Separe por Tipo de Evento

Organize seu código por tipo de evento. Cada evento pode ter uma lógica de processamento diferente.

Use Múltiplos Webhooks

Configure webhooks separados para diferentes finalidades:

Webhook	Eventos	Destino
CRM	MESSAGE_RECEIVED, CHAT_CREATED	Sistema de tickets
Satisfação	CHAT_ENDED	Pesquisa de satisfação
Alertas	CHANNEL_DISCONNECTED	Sistema de monitoramento

Checklist

Antes de ir para produção, verifique:

• [ ] URL usa HTTPS
• [ ] Resposta em menos de 30 segundos
• [ ] Processamento assíncrono implementado
• [ ] Deduplicação por webhook_id
• [ ] Tratamento de erros configurado
• [ ] Logs estruturados
• [ ] Alertas de falha configurados
• [ ] Secret Key configurada e validada
• [ ] Testes realizados com gohook.io

Recursos Relacionados

• Configuração - Como configurar webhooks
• Eventos - Lista de eventos e exemplos de payload