Skip to main content
Webhooks notificam seu sistema em tempo real quando um agendamento muda, sem que você precise fazer polling constante. Registre um endpoint HTTPS público em Minha Clínica → API e Webhooks e escolha os eventos de interesse.
A URL do endpoint precisa ser HTTPS pública. http://, localhost e endereços de rede privada são rejeitados no momento em que você salva o endpoint (e checados de novo a cada entrega) — não é possível registrar um endpoint apontando para a sua máquina local ou para uma rede interna.

​
O envelope

Todo evento chega no corpo da requisição POST nesse formato:

​
Tipos de evento

Um endpoint só recebe os eventos aos quais está inscrito. Os eventos não distinguem a origem da mudança: uma escrita feita pela API com o escopo appointments:write gera o mesmo evento que uma edição no aplicativo — inclusive para o endpoint do sistema que fez a escrita. Se o seu sistema escreve e também recebe webhooks, espere o eco das próprias escritas e trate-o de forma idempotente pelo id do agendamento em data.

​
Entrega pelo menos uma vez (at-least-once)

A entrega é pelo menos uma vez: o mesmo evento pode chegar mais de uma vez ao seu endpoint — por exemplo, se sua resposta demorar demais e a tentativa for considerada falha antes de você terminar de processá-la. O id do envelope é estável entre essas reentregas.
Faça a deduplicação pelo id do envelope e garanta que processar o mesmo evento duas vezes seja seguro (idempotente). Nunca assuma que cada id chega exatamente uma vez.

​
Responda rápido, processe depois

Responda 2xx em até 10 segundos. Se o processamento do evento (gravar no seu banco, disparar outras integrações) demorar mais que isso, enfileire o trabalho e responda 2xx imediatamente após validar a assinatura — processe de forma assíncrona depois.

​
Política de reentrega

Se seu endpoint não responder 2xx, o ByDoctor tenta novamente seguindo esta escala: 1 min → 5 min → 30 min → 2 h → 6 h Cada “falha” nessa contagem é uma entrega que já esgotou as 6 tentativas da escala acima (cerca de 8h36 de tentativas) — não uma única resposta ruim. Após 20 falhas consecutivas (ou seja, ~20 entregas seguidas totalmente esgotadas — uma indisponibilidade sustentada do seu receptor, não um erro pontual), o endpoint é desativado automaticamente e os administradores da clínica são notificados por e-mail. Um endpoint desativado não recebe novos eventos até ser reativado manualmente em Minha Clínica → API e Webhooks.

​
Evento de teste (ping)

Ao cadastrar ou editar um endpoint, use o botão de teste na interface do ByDoctor para disparar um evento ping — ele segue o mesmo envelope e a mesma assinatura de um evento real, mas com type: "ping" e um data fixo, não o formato de um agendamento:
Não trate data vazio como sinal de que é um ping — não é assim que ele se distingue; verifique o campo type do envelope. O ping é útil para validar que seu endpoint está no ar e verificando assinaturas corretamente antes de assinar eventos de produção.

​
Próximo passo

Verificação de assinatura

Valide que cada evento realmente veio do ByDoctor antes de confiar nele.