Webhooks

O que existe hoje

A camada de webhooks do Interaflow cobre principalmente o caminho de entrada — provedores externos enviando mensagens para a plataforma. O caminho de saída (Interaflow notificando seu sistema quando um evento acontece) está no roadmap, mas ainda não há configuração self-service estável.

Vamos cobrir os dois caminhos com clareza:

[Webhook de entrada]
Provedor (Gupshup, Zenvia, Omni-Bridge…)  ──►  POST /api/v1/webhooks/channels/...
 
[Webhook de saída]
Interaflow  ──►  Sua URL          (em construção)

Para receber notificações de eventos do Interaflow hoje, o caminho prático é polling via API (ver Chaves de API).

Webhooks de entrada

São os webhooks que provedores de canal disparam contra o Interaflow para entregar mensagens recebidas de contatos. Cada Canal cadastrado tem URL única para o provedor apontar.

Endpoints

Por que cada provedor é diferente

Cada provedor (Gupshup, Zenvia, Mailgun, Meta Cloud API, Baileys, etc.) envia webhook em formato proprietário. O Interaflow tem um normalizador por provedor que converte o payload bruto para o formato interno antes de despachar para o pipeline de ingestão (MessageIngestionService ou ChatRoomIngestionService para grupos).

Isso significa que você não precisa adaptar o provedor — o provedor envia no formato dele; o Interaflow normaliza.

Configurar o provedor

A configuração de “qual URL o provedor envia” varia por provedor, mas o padrão é:

1. Cadastre o Canal no Interaflow com as credenciais do provedor.
2. A UI de criação do Canal exibe a URL de webhook gerada para você copiar.
3. No painel do provedor, cole essa URL como webhook de mensagens inbound.
4. O provedor passa a entregar mensagens — o Interaflow normaliza, ingere e roteia conforme a Rota do Canal.

Detalhes específicos por provedor ficam fora do escopo desta doc; consulte a documentação do provedor escolhido.

Assinatura (HMAC)

Provedores costumam assinar o webhook com HMAC-SHA256 usando um segredo compartilhado. Quando o provedor que você usa suporta, configure o segredo nos dois lados:

• Provedor — define o segredo no painel deles.
• Interaflow — guarda o segredo na configuração do Canal (criptografado em Fernet, nunca renderizado em log).

A cada webhook recebido, o Interaflow recalcula o HMAC esperado e compara com o assinado pelo provedor. Mismatch resulta em rejeição do webhook (401/403).

Idempotência

Provedores podem redisparar o mesmo webhook quando perdem ack ou em condições de timeout. O Interaflow trata isso com chave de idempotência baseada no identificador da mensagem do provedor (channel_message_id):

• Mensagem com mesmo channel_message_id chega novamente → o Interaflow detecta duplicidade e ignora a segunda.
• Sua aplicação não vê duplicação na lista de Conversas.

Você não precisa configurar nada — é comportamento padrão do pipeline de ingestão.

Falhas e retry

Quando o Interaflow rejeita um webhook (400, 401, 403, 5xx), o provedor decide a política de retry pelo seu lado — não há retry interno do Interaflow para webhook de entrada.

Diagnóstico:

• Verifique no painel do provedor o histórico de entregas e os códigos HTTP retornados.
• Logs do Interaflow registram rejeições com motivo (assinatura inválida, payload mal formado, Canal inativo).

Webhooks de saída

Notificar seu sistema quando algo acontece no Interaflow (Conversa criada, Conversa encerrada, mensagem recebida, avaliação concluída, chamada finalizada) — esse é o caminho que a maioria das pessoas pensa primeiro quando ouve “webhooks”.

A funcionalidade de cadastro self-service de URL externa para receber esses eventos ainda não está disponível como página de admin no produto. A página citada na sidebar (Configurações → Webhooks) reflete o roadmap, mas não há configuração ativa hoje.

Caminho atual: polling

Enquanto webhooks de saída não são self-service, o padrão é:

1. Cadastre uma Chave de API no Interaflow.
2. Faça polling dos endpoints relevantes (/conversations? updated_after=..., /calls?updated_after=...) com a chave.
3. Mantenha cursor (timestamp do último poll) para não buscar tudo a cada chamada.
4. Respeite o rate limit da chave (default global ou sobrescrito por chave).

O polling cobre praticamente todos os casos de “ficar sabendo quando algo aconteceu” — só perde em latência sub-segundo (que é raramente requisito real).

Boas práticas (entrada)

• Sempre habilite assinatura HMAC quando o provedor suporta.
• Use a URL gerada na criação do Canal; não invente.
• Confirme na primeira mensagem real, não só nos pings de validação do provedor.
• Monitore o histórico de entregas no painel do provedor por alguns dias após a configuração.

Boas práticas (saída — quando vier)

Quando webhooks de saída forem disponibilizados, planeje desde já:

• Endpoint do seu lado idempotente — receber a mesma notificação duas vezes não pode duplicar dado.
• Resposta rápida (< 5 s). Trabalho pesado deve ir para fila do seu lado, não bloquear a resposta ao Interaflow.
• Logs de recepção para auditoria.
• Retry-friendly — devolva 5xx quando precisar reentrega.

Limites conhecidos

• Webhooks de saída self-service não disponíveis. Cadastro de URL para receber eventos do Interaflow ainda é roadmap.
• Sem painel unificado de logs de webhook (entrada). O histórico de entregas fica no painel do provedor; logs do Interaflow registram falhas mas não toda recepção bem-sucedida.
• Sem assinatura para todos os provedores. Provedores que não suportam HMAC entregam sem assinatura — risco mitigado por obscuridade da URL gerada.

Erros comuns

• Esperar webhook de saída funcionando porque a página existe na sidebar. Não funciona ainda — use polling.
• Apontar provedor para a URL errada. Cada Canal tem URL própria; usar URL de outro Canal entrega no lugar errado.
• Desabilitar assinatura HMAC para “facilitar”. Abre porta para spam de mensagens forjadas.
• Tentar deduplicar mensagens manualmente quando o provedor redispara. Não precisa — pipeline já dedup pelo channel_message_id.
• Apontar dois Canais para o mesmo provedor com URLs trocadas. Mensagens caem no Canal errado e quebram o roteamento.

Ver também

• Chaves de API
• Canais
• Integrações
• WhatsApp Grupos