Webhooks

Receba notificações em tempo real de mensagens recebidas e status de entrega.

Visão Geral

Webhooks permitem receber callbacks do Twilio quando mensagens são recebidas ou o status de entrega muda.

Base URL: /api/webhooks/whatsapp

Estes endpoints são públicos (sem autenticação) mas validados via header X-Twilio-Signature.

Mensagem Recebida

POST

/api/webhooks/whatsapp/webhook

Content-Type: application/x-www-form-urlencoded

Parâmetro	Tipo	Descrição
`MessageSid`	`string`	Identificador único da mensagem
`AccountSid`	`string`	ID da conta Twilio
`From`	`string`	Número do remetente (formato: `whatsapp:+5511...`)
`To`	`string`	Número do destinatário (seu número WhatsApp)
`Body`	`string`	Conteúdo da mensagem
`ProfileName`	`string`	Nome do perfil WhatsApp do remetente
`NumMedia`	`integer`	Quantidade de mídias anexadas
`MediaUrl0`	`string`	URL da primeira mídia anexada Opcional

O webhook sempre retorna HTTP 200, mesmo em caso de erro interno, para evitar retentativas do Twilio.

Status de Entrega

POST

/api/webhooks/whatsapp/status

Parâmetro	Tipo	Descrição
`MessageSid`	`string`	Identificador da mensagem
`MessageStatus`	`string`	Status: `queued`, `sent`, `delivered`, `read`, `failed`, `undelivered`
`ErrorCode`	`string`	Código de erro (quando status é `failed`/`undelivered`) Opcional
`ErrorMessage`	`string`	Descrição do erro Opcional

Teste de Webhook

POST

/api/webhooks/whatsapp/webhook/test

Endpoint para testar se os webhooks estão acessíveis.

{
  "status": "ok",
  "message": "Webhook funcionando",
  "params_recebidos": 0
}

Configuração no Twilio

As URLs de webhook devem ser configuradas no console do Twilio ou via auto-configuração do painel admin.

URLs de webhook:

Mensagens recebidas: https://seu-dominio/api/webhooks/whatsapp/webhook
Status de entrega: https://seu-dominio/api/webhooks/whatsapp/status

A URL de webhook precisa ser acessível publicamente pelo Twilio. Em ambientes sem domínio público, utilize um túnel reverso (ex: ngrok) durante a configuração inicial.

Validação de Assinatura

O Twilio assina cada requisição com HMAC-SHA1 no header X-Twilio-Signature. O servidor valida automaticamente usando o Auth Token configurado.

Atrás de proxy reverso (nginx, ALB), os headers X-Forwarded-Proto e X-Forwarded-Host são usados para reconstruir a URL original.

Se o Auth Token não estiver configurado, a validação de assinatura é desabilitada automaticamente.

Webhooks de Entrada (Inbound)

Além de receber callbacks do Twilio, a plataforma aceita webhooks de sistemas externos (n8n, Zapier, Make, integrações próprias) para acionar fluxos internos.

POST

/api/v1/webhooks/inbound/{slug}/{fluxo}

Content-Type: application/json

Parâmetro	Tipo	Descrição
`{slug}`	path	Slug da aplicação Avizuaí destino
`{fluxo}`	path	Nome livre do fluxo (para roteamento e auditoria)
`X-Avizuai-Signature`	header	Assinatura HMAC SHA-256 do payload, no formato `sha256=<hex>`. Exigida quando a aplicação tem subscription com secret configurado.
Body	JSON livre	Payload arbitrário entregue aos listeners internos

Validação HMAC

Se a aplicação destino possui ao menos uma subscription ativa com secretHmac configurado, o header X-Avizuai-Signature torna-se obrigatório.

A assinatura é calculada como HMAC-SHA256(payload_json, secret) e enviada no formato sha256=<hex_lowercase>. O servidor calcula a mesma assinatura com cada secret cadastrado e aceita se houver qualquer coincidência.

Se nenhuma subscription tem secret, o endpoint aceita sem assinatura (modo permissivo, útil para testes).

Códigos de Retorno

Status	Quando
`200 OK`	Webhook aceito e enfileirado para processamento interno
`401 Unauthorized`	Assinatura HMAC ausente ou inválida (quando obrigatória)
`404 Not Found`	Aplicação não encontrada para o slug informado
`400 Bad Request`	Payload JSON inválido

Resposta de Sucesso

{
  "aceito": true,
  "aplicacao": "minha-app",
  "fluxo": "novo-lead"
}

Próximos Passos

💬 Mensagens ⚠ Códigos de Erro