Skip to main content

Webhooks

Receba notificações automáticas sobre eventos na sua conta
Os Webhooks permitem que você receba notificações automáticas quando eventos importantes acontecem no ConnectVets Notes, como quando uma transcrição é concluída ou falha.

Como Funcionam

1

Configuração

Nossa equipe configura os webhooks no seu sistema conforme suas necessidades
2

Eventos

Quando um evento ocorre (ex: transcrição concluída), enviamos uma requisição POST
3

Recebimento

Sua aplicação recebe a notificação e pode processar o evento imediatamente
4

Confirmação

Responda com status 200 para confirmar o recebimento

Eventos Disponíveis

note.transcription.completed

Disparado quando uma transcrição é finalizada com sucesso:

note.transcription.failed

Disparado quando uma transcrição falha:

Implementação

Endpoint do Webhook

Sua aplicação deve ter um endpoint que aceite requisições POST:

Segurança

Validação de Origem

Para garantir que o webhook vem do ConnectVets, valide o header de assinatura:

HTTPS Obrigatório

  • Todos os webhooks devem usar HTTPS
  • Certificados SSL válidos são obrigatórios
  • URLs localhost não são aceitas em produção

Retry Logic

Como Funciona

Se seu endpoint não responder com status 2xx, reenviamos automaticamente:

Idempotência

Implemente verificação de duplicatas usando o webhook_id:

Monitoramento

Logs Importantes

Monitore estes aspectos:
  • Latência de resposta: Tempo para processar webhook
  • Taxa de erro: Percentual de falhas no processamento
  • Timeouts: Requisições que demoram muito
  • Duplicatas: Webhooks reprocessados

Exemplo de Logging

Configuração

Importante: Webhooks não são gerenciados via API. A configuração é feita através de contato direto com nossa equipe.

Para Configurar Webhooks

  1. Contate nossa equipe via WhatsApp (+55 31 8883-5141)
  2. Forneça informações:
    • URL do seu endpoint (deve ser HTTPS)
    • Eventos que deseja receber
    • Método de autenticação preferido
    • Ambiente (produção/desenvolvimento)

Informações Necessárias

  • URL do Endpoint: https://seuapp.com/webhooks/connectvets
  • Eventos: ["note.transcription.completed", "note.transcription.failed"]
  • Headers Customizados (opcional): Para autenticação adicional
  • Secret para Validação: Para verificar autenticidade

Teste em Desenvolvimento

Nossa equipe pode configurar webhooks para ambiente de desenvolvimento usando:
  • ngrok para túneis locais
  • Webhook.site para testes rápidos
  • RequestBin para debug

Troubleshooting

Webhook Não Recebido

Possíveis causas:
  • Endpoint inacessível (timeout/erro)
  • Certificado SSL inválido
  • Firewall bloqueando nossa IP
Soluções:
  • Verificar se endpoint responde a GET/POST
  • Validar certificado SSL
  • Liberar IPs do ConnectVets no firewall

Erro 401/403

Possíveis causas:
  • Autenticação adicional no endpoint
  • Headers de validação incorretos
Soluções:
  • Revisar lógica de autenticação
  • Verificar headers x-connectvets-signature

Webhooks Duplicados

Possíveis causas:
  • Endpoint demorou para responder (timeout)
  • Resposta não 2xx
Soluções:
  • Implementar verificação de webhook_id
  • Otimizar tempo de processamento
  • Responder rapidamente (mover processamento pesado para background)

Exemplos de Uso

Integração com CRM

Workflow de Aprovação


Próximo passo: Veja exemplos práticos de webhooks ou explore os endpoints de Notes.