Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mivicall.com/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks permitem que o vosso sistema reaja a eventos do Mivicall sem precisar de fazer polling. Quando algo acontece (marcação criada, paciente atende, chamada termina), fazemos POST ao vosso URL com o payload.

​
Configurar

Estado: implementação em construção. UI no dashboard + worker outbound em desenvolvimento. ETA: 2 semanas. Por agora, contactem support@mivicall.com para piloto.
Dashboard → Settings → Integrações → Webhooks:
  1. Click “Add endpoint”
  2. Cola o URL do vosso receiver
  3. Selecciona quais eventos queres receber (lista em Eventos)
  4. Mivicall gera um secret (whsec_...) — mostrado uma única vez
  5. Save → endpoint fica activo

​
Anatomia de um webhook

POST https://api.vosso-pms.pt/webhooks/mivicall
Host: api.vosso-pms.pt
User-Agent: Mivicall-Webhooks/1.0
Content-Type: application/json
X-Mivicall-Signature: t=1778649600,v1=5257a869e7ecebc0...
X-Mivicall-Event-Id: evt_3DZc9pK8mNqR2bC
X-Mivicall-Event-Type: appointment.created
Idempotency-Key: evt_3DZc9pK8mNqR2bC

{
  "id": "evt_3DZc9pK8mNqR2bC",
  "type": "appointment.created",
  "createdAt": "2026-05-13T14:00:00.000Z",
  "tenant": {
    "id": "3917fecd-bfe0-4cac-b629-16d80ffe28c3",
    "name": "Clínica X"
  },
  "data": {
    "appointment": {
      "id": "uuid-...",
      "professionalId": "uuid-...",
      "serviceTypeId": "uuid-...",
      "patientName": "Maria Silva",
      "patientPhoneHash": "abc123...",
      "startsAt": "2026-05-14T10:00:00+01:00",
      "endsAt": "2026-05-14T10:30:00+01:00",
      "status": "confirmed",
      "source": "voice_ai"
    }
  }
}

​
Boas práticas

1

Verificar signature

Sempre validar X-Mivicall-Signature antes de processar. Ver Verificação de signature.
2

Responder 2xx rapidamente

Devolvam HTTP 200 em menos de 5 segundos. Se o processamento é demorado, façam ack imediato e processem async (queue/worker).
3

Idempotência via Event-Id

Cada evento tem X-Mivicall-Event-Id único. Guardem-no — se chegar o mesmo ID duas vezes (retry da nossa parte), ignorem o duplicado.
4

Anti-replay com timestamp

O timestamp na signature (t=) deve estar dentro de 5 minutos do now(). Rejeitem eventos antigos.

​
Retry policy

Se o vosso endpoint responder não-2xx ou timeout (>10s):
TentativaQuando
1imediato
2+30s
3+5 min
4+30 min
5+2 horas
6+12 horas
Após 6 falhas (~14h total), marcamos o endpoint como failing. Notificamos a clínica via dashboard + email. Se 24h sem corrigir → desactivamos o endpoint.

​
Ordem dos eventos

Não é garantida em sentido estrito — webhooks podem chegar fora de ordem (rede, retries). Sempre usem data.appointment.updatedAt ou createdAt para ordenar do vosso lado. Mais robusto: ao receber evento, façam GET /v1/appointments/{id} para confirmar o estado actual antes de aplicar.

​
Testar localmente

Para desenvolvimento, podem usar:
  • ngrok: ngrok http 3000 → URL público que aponta para localhost:3000
  • smee.io: alternativa
  • Sandbox endpoint (em breve): Mivicall vai disponibilizar sandbox.mivicall.com para enviar eventos de teste

​
Encriptação em trânsito

  • HTTPS obrigatório. Endpoints HTTP plain são rejeitados.
  • TLS 1.2+ (TLS 1.3 preferido). Recusamos certificados expirados ou self-signed.
  • Mivicall verifica o vosso cert na config — se trocarem para self-signed, webhooks param.