Diska
API

Webhooks

Webhooks de saída (eventos de chamada) e de entrada suportados pela Diska.

A Diska envia webhooks de saída para os seus sistemas quando acontecem eventos (chamadas concluídas, marcações) e recebe webhooks externos para eventos assíncronos.

Webhooks de saída (eventos de chamada)

Registe endpoints via Canal API com o âmbito webhooks:manage:

POST /v1/webhook-endpoints
Authorization: Bearer dsk_…
{
  "url": "https://o-seu-sistema.com/hooks/diska",
  "events": ["call.completed"]
}

A resposta inclui o secret de assinatura (dskw_…) — guarde-o: só é mostrado uma vez.

Eventos disponíveis

EventoQuando disparaPayload
call.completedUma chamada termina com sucesso e o processamento pós-chamada conclui. Chamadas falhadas, canceladas ou abandonadas não disparam este evento.Transcrição completa, dados extraídos, avaliações, sentimento, acções executadas, call_id (utilizável em GET /v1/calls/{call_id}).
booking.createdUma marcação é criada durante uma chamada.booking_id, session_id.

Verificar a assinatura

Cada entrega inclui os cabeçalhos:

X-Diska-Event:      call.completed
X-Diska-Delivery:   <uuid único da entrega>
X-Diska-Timestamp:  <segundos unix>
X-Diska-Signature:  sha256=<hex>

A assinatura é HMAC-SHA256 do texto {timestamp}.{corpo do pedido} com o secret do endpoint:

import hashlib, hmac

def is_valid(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

Rejeite pedidos com timestamp com mais de 5 minutos para evitar replay.

Entrega e falhas

  • Responda 2xx rapidamente (ideal: enfileire e processe depois). Qualquer outra resposta conta como falha.
  • Cada entrega tenta até 3 vezes com backoff; erros 4xx (excepto 408/429) não são repetidos.
  • Após 20 falhas consecutivas o endpoint é desactivado automaticamente (disabled_reason explica). Corrija e reactive com PATCH /v1/webhook-endpoints/{id} {"active": true}.
  • Use POST /v1/webhook-endpoints/{id}/test para receber um ping assinado e validar a sua implementação.
  • A entrega é best-effort: para reconciliação, GET /v1/calls continua a ser a fonte de verdade.

Webhooks de entrada

SMS inbound

POST /api/v1/webhooks/sms/inbound

Recebe mensagens SMS do fornecedor Ombala. O body varia conforme payload do fornecedor. A API valida a origem, associa a uma sessão se existir e pode avançar o fluxo quando configurado para esperar resposta.

Configure o URL do webhook no dashboard do fornecedor:

https://api.diska.ai/api/v1/webhooks/sms/inbound

Segurança: valide assinaturas ou tokens do fornecedor quando disponíveis, use HTTPS e limite IPs de origem se o fornecedor o suportar.

Futuro

Eventos de saída adicionais (call.failed, estados de chamada em tempo real) e webhooks de entrada para Cal.com e Twilio estão planeados.

Autenticação

Chaves API para integrações e sessões Better Auth para o backoffice.

Endpoints

O Canal API para integrações e a referência da API interna.

Copyright © 2026