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.
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.
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étodo | Rota | Descrição |
|---|---|---|
POST | /webhooks/endpoints | Cadastra um endpoint (devolve o secret uma única vez) |
GET | /webhooks/endpoints | Lista 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}/ping | Envia um webhook.ping de teste |
POST | /webhooks/endpoints/{id}/rotate-secret | Gera um novo segredo de assinatura |
GET | /webhooks/endpoints/{id}/deliveries | Histórico das entregas dos últimos 2 dias |
POST | /webhooks/events/{eventId}/redeliver | Reenvia 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
- A clínica gera uma API Key com a permissão
manage_webhookse a entrega ao consumidor. - O consumidor chama
POST /webhooks/endpointscom essa chave, informando a URL em que espera receber, os eventos (event_types) e, se quiser, filtros. - A API devolve o
secret(whsec_…) uma única vez. O consumidor deve guardá-lo para verificar as assinaturas. - O consumidor testa com
POST /webhooks/endpoints/{id}/pinge confere o resultado emGET /webhooks/endpoints/{id}/deliveries.
A mesma API também é usada pela tela de administração, com token de usuário.
Eventos disponíveis
| Domínio | Eventos |
|---|---|
| Agendamentos | appointment.created, appointment.updated, appointment.doctor_changed, appointment.confirmed, appointment.queued, appointment.started, appointment.finished, appointment.canceled, appointment.no_show |
| Orçamentos | budget.created, budget.updated, budget.released, budget.paid, budget.canceled |
| Pagamentos | payment.received, payment.pending, payment.settled, payment.canceled |
| Técnico | webhook.ping (só sob demanda, pela rota de ping) |
Use ["*"] em event_types para assinar todos os tipos.
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.
| Header | Descrição |
|---|---|
webhook-id | Igual ao id do evento. Estável entre retentativas — use como chave de idempotência. |
webhook-timestamp | Unix epoch (segundos) do envio desta tentativa. |
webhook-signature | Lista, 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 dewhsec_, 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" }
}
| Campo | Descrição |
|---|---|
id | evt_ + ULID, único. |
type | <recurso>.<ação>. |
api_version | Versão do contrato (hoje 2026-10-01). |
occurred_at | Quando o fato aconteceu, ISO-8601 com o offset do fuso da conta. |
account | Conta de origem (id e subdomain). |
actor | Quem causou: user (id), api_key (uuid) ou system (id null). |
data | Snapshot completo do recurso — o mesmo formato das rotas /webhooks/resources/*. |
previous | Só os campos que mudaram, com o valor anterior. Ausente quando não se aplica. |
Resposta esperada do consumidor
| Resposta | O que o PEP faz |
|---|---|
2xx em até 10 s | Entregue. O corpo é ignorado. Recomendado: enfileirar e devolver 202. |
410 Gone | Desativa o endpoint (disabled_reason: GONE). |
408, 429, 5xx, timeout ou erro de rede | Falha transitória: tenta de novo. |
Demais 4xx | Falha 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.versionaplicado por recurso e ignore eventos comversionmenor. - 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
FAILEDe 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.
filterssó vale para eventos do domínio do filtro. Hoje existeprocedure_types, só para eventosappointment.*.
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.