Webhooks e entrega

Após cada chamada, a Hanc.AI pode enviar a chamada — resumo, transcrição, campos extraídos — para o seu próprio sistema: um sistema de tickets, um CRM, um ERP ou qualquer endpoint HTTPS. Esta página descreve exatamente como essa entrega se comporta: o que acontece quando o seu servidor está em baixo, quantas vezes voltamos a tentar, o que a sua firewall tem de permitir e qual é o aspeto do pedido.

Todos os planos

A entrega após a chamada, com novas tentativas e registo de entregas, está disponível em todos os planos, incluindo o Free.

O que é enviado e quando

O pedido é enviado assim que a chamada termina e a respetiva análise fica concluída (resumo, sentimento, os seus campos extraídos) — normalmente poucos segundos depois de desligar.

Origem	Onde se configura
Ação «Chamada de API»	Agente → Ações → Post call → Chamada de API
Passo de workflow	Editor de workflows → passo de ferramenta Chamada de API com Quando é executado: Após a chamada
Webhook do agente	O campo webhook_url do agente (referência da API)

Os pedidos que um agente faz durante uma conversa (ferramentas ao vivo) não são tratados aqui: são necessários nesse preciso segundo e nunca são repetidos mais tarde.

Quando o seu servidor está indisponível

Nada se perde. O pedido é guardado numa fila de entrega antes da primeira tentativa e permanece lá até o seu servidor o aceitar ou até o agendamento se esgotar.

• Uma entrega conta como bem-sucedida quando o seu endpoint responde com qualquer estado 2xx no prazo de 30 segundos.
• Tudo o resto é repetido: ligação recusada, erros de DNS ou TLS, tempo limite excedido e qualquer outro estado — 5xx, 429 e também 4xx. Se uma chave de API tiver expirado e a renovar, as chamadas pendentes chegam por si.
• Cada tentativa envia o mesmo pedido com o mesmo ID de entrega.

Agendamento das novas tentativas

Tentativa	Pausa anterior	Tempo desde o fim da chamada
1	— (de imediato)	~0
2	1 minuto	~1 min
3	5 minutos	~6 min
4	30 minutos	~36 min
5	2 horas	~2 h 36 min
6	6 horas	~8 h 36 min
7	24 horas	~1 dia 8 h
8	48 horas	~3 dias 8 h

São 8 tentativas ao longo de cerca de 3,4 dias — o suficiente para cobrir uma indisponibilidade durante um fim de semana.

O seu próprio agendamento

Numa ação Chamada de API (e num passo de workflow Chamada de API executado após a chamada) pode substituir o agendamento em Novas tentativas em caso de erro:

• até 10 novas tentativas,
• cada pausa de 1 minuto a 7 dias,
• remova todas as linhas para enviar uma única vez, sem novas tentativas.

Uma ação em que nunca tenha mexido segue o agendamento predefinido acima.

Após a última tentativa

A entrega é marcada como Não entregue, recebe uma notificação por email — a menos que a tenha desativado — e o pedido é conservado durante 30 dias. Durante esse período pode enviá-lo novamente — com um clique no registo de entregas ou com uma chamada à API. Também é possível enviar novamente uma entrega que já tenha sido bem-sucedida, por exemplo após um restauro do seu lado.

Independentemente de qualquer webhook, a chamada em si permanece na sua conta Hanc.AI — a transcrição, o resumo, a gravação e os campos extraídos estão disponíveis em Chamadas e através da API. Uma indisponibilidade prolongada atrasa a passagem para o seu sistema; não elimina a conversa.

Pelo menos uma vez

A entrega é feita pelo menos uma vez. Em casos raros — por exemplo, quando o seu servidor processou um pedido mas a resposta não nos chegou a tempo — a mesma chamada chega duas vezes. Use X-Hanc-Delivery-Id para reconhecer e ignorar uma repetição.

Notificações de falha

Não precisa de vigiar o registo: uma ação pode enviar-lhe um aviso por email quando o respetivo pedido não é entregue. Escolha em Notificação de falha, na ação (ou no passo de workflow):

Definição	Quando o email é enviado
Após a última tentativa (predefinição)	Uma vez, quando o agendamento das novas tentativas se esgota e o pedido é marcado como Não entregue
Após cada tentativa falhada	Após cada tentativa falhada, com a hora da seguinte — e após a última
Não notificar	Nunca; as falhas ficam visíveis apenas no registo

O email indica a ação e o agente, o host do seu servidor, o que este respondeu (por exemplo HTTP 503 ou timeout after 30s) e que tentativa foi de quantas, e inclui uma ligação para o registo de entregas. O último indica também até quando o pedido é conservado e que pode ser enviado novamente.

Enviar para define o destinatário — normalmente quem opera o sistema recetor. Se ficar vazio, o email segue para o titular da conta. É redigido no idioma da conta.

Para evitar que uma indisponibilidade inunde a sua caixa de entrada, as notificações estão limitadas por ação a 10 por hora e 30 por dia; a última antes de uma pausa indica até quando esta dura. Todas as falhas continuam a ficar registadas. Um pedido que envie novamente à mão não dá origem a notificação.

Registo de entregas

Todas as tentativas são registadas: hora, estado HTTP ou erro de rede, duração e o início da resposta do seu servidor.

Na aplicação: CRM → Comunicações → abra uma entrada do tipo Chamada de API. Vê o estado (Entregue, A repetir, Não entregue), todas as tentativas, a hora da seguinte e o botão Enviar novamente.

Através da API (autentique-se com a sua chave de API em x-api-key):

Pedido	Resultado
GET /v1/webhook-deliveries	As suas entregas, da mais recente para a mais antiga. Filtros: status (pending, delivered, failed), agent_id, call_id, limit, offset
GET /v1/webhook-deliveries/{id}	Uma entrega com todas as tentativas e o corpo do pedido
POST /v1/webhook-deliveries/{id}/resend	Envia-a novamente agora e devolve o resultado

{
  "id": "6ac71fb82e4f72e709a4a566",
  "delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
  "kind": "api_call",
  "name": "Create ticket",
  "call_id": "6ac71f9d2e4f72e709a4a4f0",
  "status": "pending",
  "attempts_made": 2,
  "attempts_max": 8,
  "next_attempt_at": "2026-10-09T11:36:04.000Z",
  "attempts": [
    { "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
    { "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
  ]
}

Os valores dos cabeçalhos do pedido armazenado (as suas chaves) nunca são devolvidos.

Rede e firewall

A Hanc.AI chama o seu endpoint — a ligação é sempre aberta do nosso lado para o seu.

Sentido	De saída a partir da Hanc.AI → de entrada do seu lado
Endereços IP de origem	178.104.10.47 (serviço de entrega) e 128.140.65.92 (serviço de chamadas, usado como alternativa)
Protocolo	HTTPS (TLS 1.2 ou superior). HTTP não cifrado funciona, mas não é recomendado
Porta	443, ou a porta indicada no seu URL
Versão de IP	IPv4
Certificado	Tem de ser válido e emitido por uma autoridade pública; os certificados autoassinados são rejeitados
Tempo de resposta	Responda no prazo de 30 segundos — idealmente, confirme a receção de imediato e processe em segundo plano
Redirecionamentos	São seguidos, até 5

Lista de permissões: se a sua firewall ou WAF filtrar por endereço de origem, autorize os dois endereços acima para o caminho do seu webhook. Anunciamos com antecedência qualquer alteração destes endereços.

Não é possível: endereços dentro de uma rede privada (10.x, 172.16–31.x, 192.168.x, localhost). O endpoint tem de estar acessível a partir da internet — diretamente ou através do seu proxy inverso / gateway de API.

Navegador: os webhooks funcionam de servidor para servidor. Não estão envolvidas definições do navegador, extensões nem portas abertas nos postos de trabalho dos colaboradores.

Formato do pedido

POST, PUT e PATCH transportam um corpo JSON (Content-Type: application/json, UTF-8).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "call_summary": "Customer reports a broken router and asks for a callback…",
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "task_achieved": true,
  "sentiment": { "sentiment": "neutral", "explanation": "…" },
  "custom_analysis_data": {
    "customer_number": "K-20417",
    "ticket_category": "Hardware",
    "priority": "high"
  },
  "collected_data": { },
  "transfer_history": [ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup"
}

Campo	Conteúdo
call_summary	Resumo da conversa
transcription	Conversa completa, intervenção a intervenção, com marcas temporais
call_from, call_to, direction	Autor da chamada, número chamado, de entrada ou de saída
start_timestamp, end_timestamp, duration	Tempo Unix e duração em milissegundos
custom_analysis_data	Os seus próprios campos, extraídos da conversa — ver Variáveis de Recolha
collected_data	Dados que o agente recolheu durante a chamada
sentiment, task_achieved	Sentimento da conversa e se o objetivo foi atingido
recording_url	Ligação para a gravação, se a gravação estiver ativa
transfer_history	Transferências ocorridas durante a chamada

Para GET e DELETE, os mesmos campos seguem na query string; os valores aninhados, como transcription, ficam de fora.

Cabeçalhos

Cabeçalho	Significado
X-Hanc-Delivery-Id	Identifica a entrega. Idêntico em todas as tentativas — use-o para ignorar duplicados
X-Hanc-Attempt	Número da tentativa, a começar em 1
X-Correlation-Id	ID de rastreio interno; indique-o quando contactar o suporte
User-Agent	HANC-Webhooks/1.0
os seus cabeçalhos	Tudo o que configurou na ação

Autenticação

Cabe-lhe decidir como o seu endpoint nos reconhece:

• Chave de API ou token — adicione um cabeçalho à ação, p. ex. Authorization: Bearer <token> ou X-API-Key: <key>. Os cabeçalhos são enviados em todas as tentativas.
• Autenticação básica — Authorization: Basic <base64(user:password)>.
• Parâmetro de consulta — para sistemas que esperam a chave no URL.
• Endereço de origem — permita apenas os endereços IP indicados acima.

Os métodos podem ser combinados; o habitual é uma chave mais uma lista de permissões de IP.

Adaptar o pedido ao seu sistema

Por predefinição, o pedido transporta a chamada completa (ver Formato do pedido). Para um sistema que espera a sua própria estrutura — como acontece com a maioria dos sistemas de tickets — cabe-lhe descrever essa estrutura e preenchê-la a partir da chamada.

Variáveis

Numa ação Chamada de API após a chamada e num passo de workflow Chamada de API, o URL, os cabeçalhos, os parâmetros de consulta e o corpo aceitam variáveis entre chavetas duplas. São preenchidas a partir da chamada imediatamente antes de o pedido sair.

Variável	Valor
{{call_id}}	ID da chamada
{{call_from}}, {{call_to}}	Autor da chamada e número chamado
{{customer_phone}}, {{customer_email}}	Número e email da outra parte, seja qual for o sentido da chamada
{{call_direction}}, {{call_type}}	inbound / outbound, phone / web
{{call_start}}, {{call_end}}	Início e fim, ISO 8601 (UTC)
{{call_duration}}	Duração em segundos
{{call_summary}}	Resumo da conversa
{{call_transcription}}	Conversa completa em texto
{{call_sentiment}}, {{call_task_achieved}}	Sentimento e se o objetivo foi atingido
{{call_recording_url}}	Ligação para a gravação
{{agent_id}}	ID do agente
os seus campos	Cada Variável de Recolha pelo respetivo nome, p. ex. {{customer_number}}, {{priority}} — e cada variável que um workflow tenha recolhido durante a chamada

Regras que convém conhecer:

• Um campo do corpo que consista apenas numa variável mantém o tipo dessa variável: "priority": "{{priority}}" é enviado como o número 3, "urgent": "{{urgent}}" como true. Texto à volta de uma variável transforma o valor em texto.
• Um valor colocado no URL recebe automaticamente codificação percentual (+43… passa a %2B43…).
• Uma variável para a qual a chamada não tem valor é enviada vazia — nunca como o literal {{name}}.

Na aplicação, o botão {x} de um campo lista as variáveis disponíveis; no corpo, ao escrever {{, as variáveis são sugeridas.

Corpo

Em Corpo (JSON), na ação, escreve o objeto JSON que o seu sistema espera, com a profundidade de aninhamento que for necessária:

{
  "ticket": {
    "subject": "Call from {{customer_phone}}: {{ticket_category}}",
    "comment": { "body": "{{call_summary}}" },
    "priority": "{{priority}}",
    "custom_fields": [
      { "id": 360001, "value": "{{customer_number}}" },
      { "id": 360002, "value": "{{call_recording_url}}" }
    ],
    "tags": ["phone-agent"]
  }
}

Apenas os seus campos

Com Enviar apenas os meus campos ativado, o pedido transporta apenas o seu corpo e os seus parâmetros de consulta — os dados da chamada não são acrescentados. Se o deixar desativado, os seus campos são enviados juntamente com a chamada completa.

Envio seletivo

Uma condição em linguagem natural («apenas se o interlocutor comunicar uma avaria») decide que chamadas desencadeiam o pedido. Várias ações podem apontar para sistemas ou endpoints diferentes.

Ligar um sistema de tickets

Qualquer sistema de tickets com uma API HTTP ou um webhook de entrada pode receber chamadas — diretamente, sem software intermédio. O que é necessário do seu lado:

1. Um endpoint acessível a partir da internet por HTTPS que aceite JSON.
2. Uma credencial para esse endpoint (chave de API, token ou autenticação básica), introduzida como cabeçalho na ação.
3. Se filtrar por endereço — os dois endereços IP acima na sua lista de permissões.

Depois, na ação:

1. Defina os seus campos. Adicione Variáveis de Recolha como número de cliente, categoria do ticket, prioridade, pedido de chamada de retorno. O agente preenche-as a partir da conversa.
2. Escreva o corpo na estrutura da API do seu sistema de tickets e coloque as variáveis nos devidos lugares.
3. Ative Enviar apenas os meus campos.
4. Clique em Testar configuração da API e, em seguida, faça uma chamada de teste.

Teremos todo o gosto em preparar consigo o corpo para o seu sistema.

Testes

Teste de ligação. O botão Testar configuração da API, na ação, envia de imediato um pedido de exemplo e mostra se o seu endpoint foi alcançado.

Teste das novas tentativas — para ver o mecanismo com os seus próprios olhos:

1. Na ação, defina um agendamento curto em Novas tentativas em caso de erro, por exemplo três pausas de 1 minuto.
2. Pare o seu endpoint ou bloqueie os nossos endereços na firewall.
3. Faça uma chamada de teste ao agente.
4. Abra CRM → Comunicações: a entrada mostra A repetir, a tentativa falhada com o respetivo erro e a hora da seguinte.
5. Volte a iniciar o endpoint (ou levante o bloqueio). A tentativa seguinte entrega a chamada e a entrada passa a Entregue — ou clique em Enviar novamente para entregar de imediato.

Lista de verificação para o seu endpoint

• Responda 2xx assim que o pedido estiver guardado; faça o trabalho pesado depois.
• Trate X-Hanc-Delivery-Id como chave de idempotência.
• Responda 4xx/5xx quando não tiver conseguido aceitar o pedido — voltaremos a tentar.
• Mantenha o certificado válido e os dois endereços de origem autorizados.