Skip to main content

Visão Geral de Webhooks

Webhooks permitem que sistemas externos recebam notificação imediata de eventos do PEP.ia (agendamentos, orçamentos e pagamentos) sem precisar consultar a API de tempos em tempos. Esta seção documenta as rotas de cadastro e operação dos endpoints que recebem esses eventos.

Autenticação necessária

Todas as rotas exigem o header Authorization: Bearer {accessToken} (token de usuário) ou x-api-key: {apiKey} (integrações), e a permissão manage_webhooks. Veja Autenticação.

Isolamento por conta (multi-tenant)

Cada conta (clínica) tem os seus próprios endpoints. Só se enxerga e se altera o que pertence à conta do token.


Base​

https://api-dev.imagemais.com.br/api/webhooks

Rotas​

MétodoRotaDescrição
POST/webhooks/endpointsCadastra um endpoint (devolve o secret uma única vez)
GET/webhooks/endpointsLista os endpoints da conta, com estatísticas das últimas 24 h
PATCH/webhooks/endpoints/{id}Altera URL, descrição, eventos, filtros ou enabled
DELETE/webhooks/endpoints/{id}Remove o endpoint
POST/webhooks/endpoints/{id}/pingEnvia um webhook.ping de teste
POST/webhooks/endpoints/{id}/rotate-secretGera um novo segredo de assinatura
GET/webhooks/endpoints/{id}/deliveriesHistórico das entregas dos últimos 2 dias
POST/webhooks/events/{eventId}/redeliverReenvia o evento às entregas que falharam
GET/webhooks/resources/appointments/{id}Estado atual de um agendamento (reconciliação)
GET/webhooks/resources/budgets/{id}Estado atual de um orçamento (reconciliação)
GET/webhooks/resources/payments/{id}Estado atual de um pagamento (reconciliação)

Fluxo de cadastro​

  1. A clínica gera uma API Key com a permissão manage_webhooks e a entrega ao consumidor.
  2. O consumidor chama POST /webhooks/endpoints com essa chave, informando a URL em que espera receber, os eventos (event_types) e, se quiser, filtros.
  3. A API devolve o secret (whsec_…) uma única vez. O consumidor deve guardá-lo para verificar as assinaturas.
  4. O consumidor testa com POST /webhooks/endpoints/{id}/ping e confere o resultado em GET /webhooks/endpoints/{id}/deliveries.

A mesma API também é usada pela tela de administração, com token de usuário.


Eventos disponíveis​

DomínioEventos
Agendamentosappointment.created, appointment.updated, appointment.doctor_changed, appointment.confirmed, appointment.queued, appointment.started, appointment.finished, appointment.canceled, appointment.no_show
Orçamentosbudget.created, budget.updated, budget.released, budget.paid, budget.canceled
Pagamentospayment.received, payment.pending, payment.settled, payment.canceled
Técnicowebhook.ping (só sob demanda, pela rota de ping)

Use ["*"] em event_types para assinar todos os tipos.

Catálogo em evolução

A lista acima é o que a API aceita em event_types. Nem todo tipo é emitido em todas as clínicas desde o primeiro dia — o contrato completo, com o formato de cada data, está em docs/webhooks/ no repositório do backend.


Como o PEP chama o consumidor​

POST {endpoint.url}
Content-Type: application/json; charset=utf-8
User-Agent: PEPia-Webhooks/1.0
webhook-id: evt_01JA2Z3X4Y5W6V7U8T9S0R1Q2P
webhook-timestamp: 1759766400
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

O padrão é o Standard Webhooks, com bibliotecas de verificação prontas em várias linguagens.

HeaderDescrição
webhook-idIgual ao id do evento. Estável entre retentativas — use como chave de idempotência.
webhook-timestampUnix epoch (segundos) do envio desta tentativa.
webhook-signatureLista, separada por espaço, de assinaturas v1,<base64>. Há mais de uma durante a rotação de segredo.

Assinatura​

conteudo_assinado = "{webhook-id}.{webhook-timestamp}.{corpo_bruto}"
assinatura = base64( HMAC_SHA256( segredo_decodificado, conteudo_assinado ) )
  • O segredo tem o formato whsec_<base64 de 32 bytes>. A chave do HMAC é o trecho depois de whsec_, decodificado de base64.
  • Use o corpo bruto (antes do parse) e compare em tempo constante.
  • Aceite se qualquer assinatura da lista bater e rejeite se |agora - webhook-timestamp| passar de 5 minutos.

Envelope​

{
"id": "evt_01JA2Z3X4Y5W6V7U8T9S0R1Q2P",
"type": "appointment.queued",
"api_version": "2026-10-01",
"occurred_at": "2026-10-06T14:32:10.123-03:00",
"account": { "id": 12, "subdomain": "clinica-x" },
"actor": { "type": "user", "id": 345 },
"data": { "object": "appointment", "id": 98765, "version": 1759771930123 },
"previous": { "status": "CONFIRMED" }
}
CampoDescrição
idevt_ + ULID, único.
type<recurso>.<ação>.
api_versionVersão do contrato (hoje 2026-10-01).
occurred_atQuando o fato aconteceu, ISO-8601 com o offset do fuso da conta.
accountConta de origem (id e subdomain).
actorQuem causou: user (id), api_key (uuid) ou system (id null).
dataSnapshot completo do recurso — o mesmo formato das rotas /webhooks/resources/*.
previousSó os campos que mudaram, com o valor anterior. Ausente quando não se aplica.

Resposta esperada do consumidor​

RespostaO que o PEP faz
2xx em até 10 sEntregue. O corpo é ignorado. Recomendado: enfileirar e devolver 202.
410 GoneDesativa o endpoint (disabled_reason: GONE).
408, 429, 5xx, timeout ou erro de redeFalha transitória: tenta de novo.
Demais 4xxFalha definitiva desta entrega: sem retentativa; pode ser reenviada manualmente.

Garantias e retentativas​

  • At-least-once: o mesmo evento pode chegar mais de uma vez. Deduplique por webhook-id.
  • Sem ordem garantida: guarde o último data.version aplicado por recurso e ignore eventos com version menor.
  • Retentativas: imediata, 5 s, 30 s, 2 min, 10 min, 30 min, 1 h, 3 h e 6 h (9 tentativas, cerca de 11 h). Esgotadas, a entrega fica FAILED e pode ser reenviada.
  • Retenção: eventos e entregas ficam 2 dias. Um endpoint que passa 2 dias só falhando é desabilitado (disabled_reason: FAILING).

Regras de cadastro​

  • Máximo de 10 endpoints por conta.
  • A URL precisa ser https:// em produção.
  • URLs que resolvem para rede interna (loopback, faixas privadas, link-local) são rejeitadas, salvo hosts liberados por configuração.
  • filters só vale para eventos do domínio do filtro. Hoje existe procedure_types, só para eventos appointment.*.

Reconciliação​

Como a entrega não é ordenada e pode falhar por horas, o consumidor pode reconsultar o estado atual de um recurso por id nas rotas /webhooks/resources/*, que devolvem o mesmo formato do data dos eventos.