Webhooks #

Os webhooks permitem que o Your AI Connector notifique automaticamente as suas outras ferramentas de negócio sempre que algo importante acontece — um novo contacto criado, um agendamento marcado, uma mensagem recebida. Em vez de verificar manualmente por atualizações, os seus sistemas ligados recebem uma notificação instantânea no momento em que algo acontece.

O que são Webhooks? #

Pense num webhook como uma mensagem de texto automática entre duas aplicações. Quando algo acontece no Your AI Connector (como um novo contacto a registar-se), a plataforma envia instantaneamente uma notificação para outro sistema à sua escolha. Fornece um endereço web (chamado “URL de webhook”) para onde estas notificações devem ser enviadas — este é normalmente fornecido pelo seu CRM, plataforma de automatização ou programador.

A página de Webhooks apenas envia dados PARA FORA do Your AI Connector. Os webhooks configurados aqui funcionam num sentido, do Your AI Connector para as suas outras ferramentas. Para trazer um novo lead ou outros dados PARA DENTRO (a partir de um formulário de site, do seu CRM ou do GoHighLevel), tem duas opções. Uma Automação com o gatilho Webhook fornece um endereço web para o qual o seu formulário ou ferramenta pode enviar dados, e os seus passos podem então criar o contacto, enviar uma mensagem e muito mais. Ou o seu sistema faz uma chamada de API, por exemplo a operação Criar um Contacto, utilizando a sua chave de API; consulte Acesso à API e Funis.

Os webhooks fazem parte apenas de alguns planos. Se o seu plano não incluir webhooks, a página Webhooks não estará disponível e não serão enviados eventos. Tudo o que guardou anteriormente permanece na sua conta e começará a ser enviado novamente assim que mudar para um plano que inclua webhooks. As funcionalidades do seu plano estão listadas na sua página de faturação e o seu fornecedor pode indicar-lhe para que plano deve mudar.

As utilizações comuns incluem:

• Sincronizar novos contactos com o seu CRM.
• Acionar um fluxo de trabalho no Zapier, Make ou Pabbly quando uma etiqueta é aplicada.
• Notificar a sua equipa no Slack quando um humano é alertado.
• Atualizar o seu sistema de calendário quando uma reunião é agendada.
• Registar resumos de conversas na sua base de dados.

Configurar Webhooks #

1. Na barra lateral esquerda, clique em Definições (ícone de engrenagem).
2. Na barra lateral de Definições, sob o grupo Integrações, clique em Webhooks.

Numa conta sem webhooks configurados, a página tem este aspeto:

3. Clique em New webhook, no canto superior direito. Abre-se um formulário na página:

4. Preencha:
   • URL de Endpoint — o endereço web para o qual o Your AI Connector enviará notificações de eventos. Obtém este endereço do seu sistema externo (CRM, plataforma de automatização ou servidor personalizado).
   • Nome — uma etiqueta que reconhecerá mais tarde (por exemplo, “Alertas Slack” ou “Sincronização CRM”). Apenas para sua referência.

O seu URL de webhook deve ser um endereço https:// publicamente acessível. Endereços http:// simples, localhost ou endereços de rede privada e endereços internos da plataforma são rejeitados ao guardar. Para testar a partir da sua própria máquina, utilize um túnel público (webhook.site ou ngrok) em vez de localhost.

5. Em Eventos, clique nos eventos que pretende que este webhook receba — todos os 24 estão listados em Os 24 Eventos de Webhook.
6. (Opcional) Ative Tentar novamente entregas falhadas se quiser que o Your AI Connector continue a tentar após uma falha temporária — consulte Tentar Novamente Entregas Falhadas.
7. Clique em Criar webhook. Este aparece na lista abaixo do formulário e pode clicar em Testar na respetiva linha a qualquer momento para enviar um payload de exemplo para o seu endpoint.

Permissão necessária. Adicionar, editar ou testar webhooks requer a permissão de “edição” de Integrações (os membros da equipa com permissão apenas de visualização verão um aviso de leitura apenas em vez do formulário).

Assinar um webhook requer que este já tenha sido guardado primeiro — abra a linha de um webhook existente para o editar e o painel Segredo de assinatura aparecerá na parte inferior do formulário de edição. Um rascunho novo e não guardado ainda não tem opção de assinatura — consulte Payloads Assinados abaixo.

Um Webhook para Todas as Suas Contas de Cliente (Agências) #

Se gere uma agência, não precisa de recriar o mesmo webhook em cada conta de cliente. Na conta de agência, o formulário de webhook tem um botão de alternância adicional: Também disparar para todas as contas de cliente. Ative-o e este webhook receberá também eventos que ocorram em todas as contas de cliente sob a sua agência — um endpoint, toda a agência.

Como funciona:

• O bloco user indica-lhe a que cliente pertence um evento. Cada notificação já contém um bloco user que identifica a conta onde o evento ocorreu, para que a sua automatização possa encaminhar por cliente.
• As definições do seu webhook aplicam-se a todo o lado. Os eventos que selecionou, o segredo de assinatura e a definição de nova tentativa são também utilizados para as entregas das contas de cliente.
• Sem entregas duplicadas. Se uma conta de cliente tiver o seu próprio webhook a apontar para o mesmo URL, esse será utilizado para os eventos dessa conta — o mesmo evento nunca chega duas vezes ao mesmo endpoint.
• Os clientes não o veem. O webhook não aparece na página de Webhooks da própria conta do cliente e os clientes não o podem desativar — é da sua responsabilidade geri-lo.
• A fiabilidade é monitorizada por conta de cliente. Se o seu endpoint continuar a falhar, é automaticamente desativado para a conta cujas entregas falharam (consulte Fiabilidade do Webhook), e não para toda a agência de uma só vez.

O botão de alternância apenas aparece em contas de agência. A sua configuração através da API também é suportada — consulte o campo apply_to_sub_accounts na API de Webhooks.

Eventos de Acionamento Disponíveis #

Pode ativar ou desativar cada um dos 24 eventos de webhook de forma independente. Quando um evento é disparado, o Your AI Connector envia uma notificação para o seu URL de webhook com os dados relevantes. Cada evento, o seu significado e o código event que coloca no payload estão listados em conjunto em Os 24 Eventos de Webhook mais abaixo nesta página.

É bom saber: Tarefa Criada, Tarefa Atualizada e Tarefa Concluída são totalmente selecionáveis e guardam corretamente. Resumo Diário Criado é também uma adição recente. Consulte Webhook de Tarefa Concluída abaixo para ver a estrutura desse payload.

Acionadores de Webhook Baseados em Etiquetas #

subscribed_to_tags não limita os eventos de um webhook a uma etiqueta. Apenas restringe quais as etiquetas que produzem uma notificação de resumo de conversação. Para receber um pedido quando uma etiqueta específica é aplicada, defina um URL de webhook nessa etiqueta no separador Etiquetas do editor de agentes.

O formulário de webhook em si não tem um seletor de etiquetas, nem ao criar um novo webhook nem ao editar um existente, pelo que o subscribed_to_tags só pode ser lido ou alterado através da API de Webhooks, ou pedindo ao suporte.

É bom saber: editar um webhook existente que tenha uma lista subscribed_to_tags (mudar o nome, alterar os eventos, alternar as tentativas) já não limpa essa lista — uma vez que o formulário não tem um seletor de etiquetas para enviar de volta, guardar a partir desta página deixa agora a lista existente intacta. (Isto era um erro real antes de 21 de julho de 2026: guardar a partir do formulário de webhook costumava apagar a lista porque enviava sempre uma lista de etiquetas vazia. Se um webhook perdeu a sua lista subscribed_to_tags antes dessa data, terá de ser reconfigurado através da API.)

Gerar Resumo para Contactos Etiquetados #

Onde um webhook tem uma lista subscribed_to_tags, pode ativar Gerar Resumo. Quando ativado, o Your AI Connector gera automaticamente um resumo da conversação para o contacto quando uma dessas etiquetas é aplicada e inclui-o nos dados do webhook — contexto completo sem necessidade de um pedido separado.

Testar o seu Webhook #

1. Abra Definições → Integrações → Webhooks.
2. Na linha do seu webhook, clique em Testar.
3. Verifique o seu sistema externo para confirmar que recebeu os dados de teste.
4. Reveja o formato dos dados para garantir que o seu sistema os consegue analisar corretamente.

Para um teste completo de ponta a ponta, envie uma mensagem que acionaria um dos seus eventos configurados (uma difusão ou uma mensagem recebida num canal ligado) e verifique se o webhook é acionado com os dados reais.

O que conta como uma entrega bem-sucedida #

Quer clique em Testar ou o evento seja disparado a sério, enviamos a mesma coisa:

• Um pedido POST (nunca GET), com o corpo em JSON e Content-Type: application/json.
• Os cabeçalhos listados em Payloads Assinados. Os cabeçalhos de assinatura só são incluídos depois de definir um segredo de assinatura.

Consideramos a entrega bem-sucedida quando:

• O seu endpoint responde com qualquer estado 2xx (200, 201, 204 — tudo serve).
• Responde dentro de 30 segundos.

Algumas coisas que surpreendem as pessoas:

• O corpo da resposta é ignorado. Não precisa de devolver qualquer JSON específico. Um 200 vazio é suficiente.
• Os redirecionamentos contam como uma falha. Não os seguimos, por isso um 301 ou 302 (incluindo um redirecionamento de barra final, ou de http para https) é registado como uma entrega falhada. Guarde o URL final, não um que redirecione.
• As query strings são totalmente suportadas. https://your-app.com/hook?token=abc123 é enviado exatamente como o guardou, por isso colocar um token na query string funciona tão bem como colocá-lo no caminho.
• O seu URL deve ser https:// e publicamente acessível. Endereços que pertencem à própria infraestrutura da Your AI Connector são rejeitados, mas os seus próprios endpoints no Google Cloud Functions, Cloud Run, App Engine, Firebase Hosting ou em qualquer outro lugar são aceites.
• Uma firewall ou camada de proteção contra bots à frente do seu endpoint pode bloquear-nos. O caso mais comum é o Cloudflare: se a sua zona tiver o Bot Fight Mode ou um desafio gerido ativado, o nosso pedido recebe uma página de desafio “Just a moment…” com um 403 em vez de chegar ao seu servidor — e um pedido servidor-para-servidor nunca pode passar um desafio de navegador, pelo que tanto o botão Testar como os eventos reais falham da mesma forma. O botão Testar dir-lhe-á quando isto estiver a acontecer (“Cloudflare is showing a bot challenge to our request”). Corrija-o no Cloudflare com uma regra de Segurança / WAF que ignore os desafios para o seu caminho de webhook (ou para o agente de utilizador Webhook-Delivery/1.0), e depois clique em Testar novamente.
• Se a sua firewall precisar de uma lista de permissões de IP em vez disso (por exemplo, o plano gratuito do Cloudflare, onde o Bot Fight Mode simples não pode ser ignorado por uma regra WAF, mas uma Regra de Acesso IP definida como Permitir é executada antes), podemos ajudar: cada entrega, seja a partir do botão Testar ou de um evento em direto, é enviada a partir de um endereço IPv4 fixo (sem intervalos, sem IPv6, sem rotação). Contacte o suporte e dar-lhe-emos o endereço para adicionar à lista de permissões. Mantenha a verificação de assinatura como a sua verificação de confiança real, uma vez que valida cada payload independentemente de onde veio.
• O resultado do Teste diz-lhe exatamente o que o seu endpoint respondeu. Um teste falhado mostra agora a razão real (o estado HTTP que o seu endpoint devolveu, um tempo limite, ou que não conseguimos chegar ao endereço de todo) em vez de um erro genérico, e um teste num webhook guardado é enviado assinado quando a assinatura está ativada, exatamente como um evento em direto.

Utilizar o n8n, Make ou Zapier (“Test URL” vs “Production URL”) #

As plataformas de automação fornecem normalmente dois endereços de webhook diferentes, e isto causa confusão:

• Um URL de Teste (no n8n contém /webhook-test/). Este apenas recebe dados enquanto estiver a observar ativamente o canvas e tiver acabado de clicar em Ouvir evento de teste (ou Testar fluxo de trabalho). Captura um único evento e depois para de ouvir — por isso, clicar em Testar no Your AI Connector várias vezes seguidas apenas apanha o primeiro, e apenas se a janela de escuta estiver ativa nesse preciso momento. Para testar: clique primeiro em Ouvir evento de teste no n8n, depois volte ao Your AI Connector e clique em Testar uma vez.
• Um URL de Produção (no n8n contém /webhook/, sem -test). Este é o que deve colar no Your AI Connector para eventos em direto. Só funciona quando o seu fluxo de trabalho estiver definido como Ativo. Se o fluxo de trabalho não estiver ativo, o n8n rejeita o pedido com um erro “404 / webhook not registered”, mesmo que o Your AI Connector tenha enviado os dados corretamente.

Em resumo: teste com o URL de Teste enquanto ouve, mas para que o webhook continue a funcionar com contactos reais, guarde o URL de Produção no Your AI Connector e certifique-se de que o fluxo de trabalho está Active.

Formato de Dados do Webhook #

Quando um webhook é disparado, o Your AI Connector envia dados estruturados (JSON) para o seu URL de webhook. Se estiver a utilizar uma plataforma de automatização como o Zapier ou o Make, esta analisa estes dados automaticamente por si. Se estiver a criar uma integração personalizada:

{
  "event": "contactCreated",
  "contact": { "id": "<contact-id>", "first_name": "Jane", "...": "..." },
  "campaign": { "id": "<campaign-id>", "name": "AI Receptionist", "status": "Live" },
  "agent": { "id": "<agent-id>", "name": "Front Desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" }
}

Leia agent, não campaign. As campanhas foram movidas para Agentes de IA e Transmissões (ver As Campanhas Foram Movidas), pelo que os seus contactos estão associados a um agente e agent indica-lhe qual deles geriu a conversação. O campo campaign ainda é enviado para que os recetores mais antigos continuem a funcionar, mas é normalmente null; só é preenchido para um contacto que ainda mantém uma ligação a uma campanha clássica. Não assuma que campaign está sempre presente.

O bloco agent chegou a 15 de agosto de 2026. Situa-se ao lado de campaign nos eventos ligados a uma conversação — um chat concluído, não incomodar, uma retoma, um desarquivamento, uma pausa de IA, uma nova mensagem, um resumo de conversação e o webhook que pode definir numa etiqueta — e transporta o id e name do agente responsável, ou null quando não está envolvido nenhum agente. É puramente aditivo: todos os campos que já recebe permanecem inalterados, pelo que um recetor que tenha criado antes dessa data continuará a funcionar sem necessidade de atualizações.

Alguns eventos adicionam o seu próprio bloco de nível superior extra. Por exemplo, Marcação Agendada, Marcação Cancelada e Marcação Reagendada adicionam um bloco appointment (consulte Webhook de Marcação Agendada), Nova Mensagem adiciona um bloco message completo com o texto (consulte Webhook de Nova Mensagem), e Entregas e Leituras adicionam um bloco message curto apenas com o ID e o estado da mensagem (consulte Webhook de Entregas e Leituras).

As Entregas e Leituras indicam-lhe qual a mensagem, mas não o seu conteúdo. Contêm um bloco message com o id e o status da mensagem — e esse id é o mesmo messageId que o endpoint de envio de mensagem devolve, para que possa fazer corresponder um recibo de entrega ou leitura à mensagem exata que enviou — mas não contêm o corpo da mensagem. Replies (Respostas) não contém qualquer bloco message. Se precisar das palavras que foram enviadas ou recebidas, subscreva New Message (Nova Mensagem) em conjunto com estes.

Duas coisas a saber antes de escrever o seu recetor. Não existe um campo timestamp, nem um wrapper data. Cada bloco situa-se ao nível superior do objeto JSON, como mostrado acima.

Os 24 Eventos de Webhook #

Os 24 eventos de webhook, com a etiqueta de visualização que seleciona na aplicação e o código event enviado no payload. O código event é uma string curta que não corresponde à etiqueta de visualização, por isso, faça a correspondência no seu recetor com base no código, não na etiqueta:

Dois outros códigos nunca aparecem nessa lista porque não subscreve esses eventos: contact_tags_updated, enviado por um URL de webhook definido numa etiqueta individual, e summary_generated, enviado quando um resumo de chat é escrito para uma etiqueta na lista subscribed_to_tags de um webhook.

Canal Ligado ainda não é enviado. Aparece na lista de eventos, mas nada o emite atualmente. Não desenvolva com base nele.

As notificações baseadas em etiquetas e tarefas utilizam as suas próprias formas separadas. Consulte Etiquetas de Contacto Atualizadas e Tarefa Concluída.

Webhook de Contacto Criado #

Enviado quando o evento Contacto Criado é acionado (um novo contacto é adicionado manualmente, via importação ou via API).

Nome do evento #

contactCreated

Formato do payload #

{
  "event": "contactCreated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

A amostra “Teste” e um evento real parecem ligeiramente diferentes. O botão de teste envia dados de marcador de posição (John Doe, um bloco de campanha de amostra). Um evento de Contacto Criado real transporta os detalhes reais do contacto, e alguns campos podem estar vazios dependendo do canal.

Webhook de Nova Mensagem #

Este webhook é disparado sempre que uma mensagem é adicionada a uma conversação, em qualquer canal. Abrange ambas as direções: mensagens que o seu contacto lhe envia e mensagens que o seu agente de IA, a sua equipa ou uma transmissão lhes envia. É o único webhook que inclui o texto da mensagem, por isso é o que deve utilizar quando pretende espelhar conversações num sistema externo.

Nome do evento #

new_message

Formato do payload #

{
  "event": "new_message",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null,
    "is_bot_active": true,
    "ad_referral": null,
    "ad_attribution": null
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "body": "Hi, are you open on Saturday?",
    "direction": "inbound",
    "status": "received",
    "created_at": "2026-07-30T17:27:06.000Z",
    "channel": "whatsapp_web",
    "media_url": null,
    "media_content_type": null
  }
}

Ainda não existe nenhum bloco campaign neste payload. Nova Mensagem envia contact, agent, user e message. O bloco agent foi adicionado a 15 de agosto de 2026 e indica-lhe qual o agente que gere a conversação; se precisar de mais contexto sobre o contacto, consulte-o através da API utilizando contact.id.

Guarde os anexos pouco tempo depois de chegarem. A ligação media_url deixa de funcionar 7 dias após a chegada da mensagem, em todos os canais (WhatsApp Business API, WhatsApp Web, Instagram, Messenger, Telegram, widget de chat e os restantes); o ficheiro em si permanece. Para obter uma nova ligação mais tarde, invoque Transferir o anexo de uma mensagem com contacts/{contact.id}/messages/{message.id}. Os campos foram adicionados a 13 de setembro de 2026.

Quando media_url é null mas o corpo indica que chegou um ficheiro. Alguns anexos são armazenados de uma forma que não tem uma ligação direta, e uma partilha de um reel, publicação ou menção de story do Instagram é uma ligação para o Instagram, não um ficheiro, pelo que esses também chegam como null (o corpo indica o que foi partilhado). Para um ficheiro, chame Download a message’s attachment com o ID da mensagem para obter uma ligação.

O histórico importado não dispara este webhook. Quando um número do WhatsApp Web importa as suas conversas anteriores, essas mensagens mais antigas são guardadas sem uma notificação de Nova Mensagem para cada uma.

Os registos internos da IA não disparam este webhook. Juntamente com as mensagens reais, a plataforma mantém as suas próprias linhas de registo numa conversa (as chamadas de ferramentas da IA e registos internos de turnos). Essas nunca são enviadas — apenas recebe mensagens que foram genuinamente enviadas ou recebidas.

Webhook de Entregas e Leituras #

Estes dois eventos reportam o que aconteceu a uma mensagem depois de ter saído de Your AI Connector: Deliveries (Entregas) dispara quando uma mensagem chega ao contacto (ou falha ao chegar), e Reads (Leituras) dispara quando o contacto a abre, nos canais que suportam recibos de leitura.

Ambos contêm um bloco message com o ID da mensagem a que o evento se refere, para que possa fazer corresponder a atualização à mensagem exata que enviou.

Nomes de eventos #

delivered e undelivered para Deliveries (Entregas), read para Reads (Leituras).

Formato do payload #

{
  "event": "delivered",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "ad_referral": null,
    "ad_attribution": null
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<message-id>",
    "status": "delivered"
  }
}

Como fazer corresponder uma atualização à mensagem que enviou. Guarde o messageId que recebe quando envia uma mensagem através da API. Quando chegar uma notificação de Deliveries ou Reads, procure esse ID guardado em message.id no payload — esse é o seu recibo de entrega ou leitura para essa mensagem exata.

Não existe texto de mensagem aqui. O bloco message contém apenas o ID e o estado. Subscreva New Message se também precisar do corpo da mensagem.

O bloco message só está presente quando sabemos de que mensagem se tratava. Na rara atualização que não conseguimos associar a uma mensagem guardada, o bloco é omitido em vez de ser enviado vazio — por isso, verifique se message existe antes de ler message.id.

Uma notificação por alteração de estado. Uma única mensagem enviada produz normalmente uma notificação delivered e, depois, em canais com recibos de leitura, uma notificação read. Um envio falhado produz undelivered em vez disso.

Webhook de Marcação Agendada #

É acionado quando um contacto marca uma reunião. É acionado da mesma forma, quer a IA a tenha marcado durante uma conversa, quer a tenha marcado manualmente, ou tenha chegado através da API.

Nome do evento #

booked

Formato do payload #

{
  "event": "booked",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "campaign": {
    "id": "<campaign-id>",
    "name": "AI Receptionist",
    "status": "Live"
  },
  "user": {
    "id": "<account-id>",
    "email": "owner@example.com"
  },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": null,
    "external_reference": "crm-booking-1042",
    "event": {
      "id": "<service-id>",
      "event_name": "Intro Call",
      "slot_duration": 30,
      "location": "Zoom",
      "meeting_link": "https://...",
      "event_type": "online"
    }
  }
}

O google_calendar_event_id é frequentemente null neste webhook, e isso é normal. O evento do Google Calendar é criado no mesmo momento em que esta notificação é enviada, pelo que o ID geralmente ainda não está pronto. Volte a obter a marcação pelo seu appointment_id um momento depois, se precisar dele. Permanece null permanentemente se a conta não tiver um Google Calendar ligado, por isso não espere por ele indefinidamente.

O botão “Testar” envia um bloco appointment de exemplo com valores fictícios, para que possa desenvolver com base na estrutura antes de chegar uma marcação real.

Dois casos em que este webhook não é disparado: marcações importadas de um calendário externo e reservas que chegam através da integração Formitable.

Webhooks de Marcação Cancelada e Reagendada #

Marcação Cancelada dispara quando uma marcação é cancelada, e Marcação Reagendada dispara quando esta é movida para uma nova hora de início ou fim. Ambos disparam da mesma forma, quer a IA o tenha feito durante uma conversação, quer tenha sido alterado por si na aplicação, via API ou se alguém alterou o evento no Google Calendar ligado.

Nomes de eventos #

appointment_cancelled e appointment_rescheduled

Formato do payload #

O corpo é o mesmo que em Marcação Agendada, com a marcação tal como está após a alteração. Um cancelamento adiciona appointment.cancelation_reason; um reagendamento adiciona um bloco previous de nível superior com as horas antigas:

{
  "event": "appointment_rescheduled",
  "contact": { "id": "<contact-id>", "email": "jane@example.com", "phone_number": "+15551234567", "first_name": "Jane", "last_name": "Smith" },
  "campaign": null,
  "agent": { "id": "<agent-id>", "name": "Front desk" },
  "user": { "id": "<account-id>", "email": "owner@example.com" },
  "appointment": {
    "appointment_id": "<appointment-id>",
    "start_time": "2026-07-21T09:00:00.000Z",
    "end_time": "2026-07-21T09:30:00.000Z",
    "status": "Confirmed",
    "room_name": "Room 1",
    "description": "Discovery call",
    "summary": "30 min intro",
    "google_calendar_event_id": "<calendar-event-id>",
    "external_reference": "crm-booking-1042",
    "cancelation_reason": null,
    "event": { "id": "<service-id>", "event_name": "Intro Call", "slot_duration": 30 }
  },
  "previous": {
    "start_time": "2026-07-20T15:00:00.000Z",
    "end_time": "2026-07-20T15:30:00.000Z"
  }
}

Uma alteração, um evento. Cancelar uma marcação envia apenas Marcação Cancelada, mesmo que a sua hora tenha sido alterada na mesma edição. Editar apenas o título, notas ou sala não envia nenhum. Mover a mesma marcação duas vezes envia dois eventos de Marcação Reagendada.

Webhook de Conversação Concluída #

Disparado quando a IA decide que uma conversação chegou ao fim (uma reserva efetuada, um lead desqualificado, etc.).

Nome do evento #

chat_concluded

Formato do payload #

O payload transporta event, o contact completo, o agent que geriu o chat e a conta user. Também transporta conversation_cost, o custo desta conversação em créditos, para que um fluxo n8n ou Make possa registá-lo sem uma segunda chamada:

{
  "event": "chat_concluded",
  "contact": { "id": "abc123", "first_name": "Jane", "channel": "whatsapp" },
  "agent": { "id": "agent_1", "name": "Sales Agent" },
  "user": { "id": "user_1" },
  "conversation_cost": {
    "credits": 7.5,
    "session_id": "sess_9f2",
    "started_at": "2026-09-26T09:14:02.000Z",
    "outcome": "contained"
  }
}

• credits: créditos cobrados nesta conversação, com os reembolsos deduzidos. É contabilizado da mesma forma que o relatório de custos de conversação na API.
• outcome: contained (a IA geriu-a sozinha), handed_off (alguém da sua equipa respondeu após a IA, ou a IA alertou um humano) ou no_ai.
• conversation_cost é omitido quando o valor não pode ser calculado nesse momento. Trate-o como opcional.

Webhook de Etiquetas de Contacto Atualizadas #

Disparado quando uma etiqueta é aplicada a um contacto, e essa etiqueta tem um URL de webhook configurado no agente a que o contacto está atribuído.

Nome do evento #

contact_tags_updated

Quando é acionado #

• É aplicada uma etiqueta a um contacto que tem um agente de IA atribuído.
• Pelo menos uma das etiquetas aplicadas tem um URL de webhook definido no separador Etiquetas do editor desse agente.

Um contacto que ainda mantém uma ligação a uma campanha clássica de antes da mudança para agentes é um caso especial: se as etiquetas dessa campanha tiverem URLs de webhook, esses são utilizados; caso contrário, são utilizados os do agente.

Se forem aplicadas várias etiquetas com URLs de webhook diferentes na mesma atualização, é enviado um pedido por URL, contendo cada um apenas as etiquetas que correspondem a esse URL.

A remoção de uma etiqueta nunca envia um pedido. A maioria das pessoas aponta estes URLs para uma ação — cobrar um depósito, reservar um horário, alertar um representante — pelo que uma etiqueta removida de um contacto costumava voltar a executar essa ação. Já não o pode fazer. Uma remoção continua a aparecer em removed_tags quando ocorre na mesma atualização que uma aplicação que vai para o mesmo URL, pelo que uma automatização que lê ambos os arrays mantém a visão completa; o que nunca verá é um pedido causado apenas por uma remoção. (Alterado a 12 de agosto de 2026. Antes dessa data, as remoções também enviavam um pedido.)

Formato do payload #

{
  "event": "contact_tags_updated",
  "contact": {
    "id": "<contact-id>",
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "is_bot_active": true,
    "ad_referral": {
      "ctwa_clid": "ARAbc123...",
      "source_id": "120210000000000",
      "source_type": "ad",
      "source_url": "https://fb.me/xxxx",
      "headline": "Get 20% off today",
      "body": "Message us now to claim your discount",
      "channel": "whatsapp"
    },
    "ad_attribution": null
  },
  "added_tags": ["qualified-lead"],
  "removed_tags": ["new-lead"],
  "agent": {
    "id": "<agent-id>",
    "name": "Front Desk"
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  }
}

Testar um webhook de etiqueta #

Junto ao campo do URL do webhook no separador Etiquetas, existe um botão Testar. Este envia imediatamente um payload de exemplo para esse URL, para que possa confirmar que a sua automatização o recebe antes de esperar por uma conversa real.

O teste envia a mesma estrutura contact_tags_updated apresentada acima, utilizando um contacto de marcador de posição, com a etiqueta que está a testar em added_tags e um removed_tags vazio. O que a sua automatização vê no teste é o que verá em produção.

Duas coisas a saber:

• Guarde a etiqueta primeiro. O teste procura a etiqueta pelo seu nome guardado, por isso uma etiqueta nova ou uma renomeação não guardada ainda não pode ser testada. O botão permanece cinzento até que o nome no ecrã corresponda ao guardado.
• Um teste falhado não conta contra o seu webhook. Os testes nunca contribuem para a desativação automática após falhas repetidas descrita em Fiabilidade do Webhook.

Se o teste falhar, a mensagem indica-lhe o que o seu endpoint respondeu (por exemplo, um 404 ou 500), o que é geralmente suficiente para detetar um URL incorreto ou um fluxo de trabalho que não está ativado.

Webhook de Tarefa Concluída #

Apenas para referência. Os webhooks de tarefas (como dados) estão documentados aqui para programadores; os eventos Tarefa Criada, Tarefa Atualizada e Tarefa Concluída são selecionáveis na lista de eventos padrão no formulário de webhook como qualquer outro evento — consulte Eventos de Disparo Disponíveis e Os 24 Eventos de Webhook.

Este payload é enviado quando uma tarefa transita para uma fase marcada como fase de conclusão. Uma tarefa que se mova entre fases que não sejam de conclusão envia o formato taskUpdated em vez disso.

Nome do evento #

taskCompleted

Quando é acionado #

• Uma tarefa é atualizada.
• O seu valor stage mudou em comparação com o valor anterior.
• A nova fase está configurada como uma fase de conclusão nas definições de fase de tarefas da conta.

Formato do payload #

{
  "event": "taskCompleted",
  "contact": {
    "email": "jane@example.com",
    "phone_number": "+15551234567",
    "first_name": "Jane",
    "last_name": "Smith",
    "human_alerted": false,
    "human_alert_reason": null
  },
  "user": {
    "email": "owner@example.com",
    "first_name": "Alex",
    "last_name": "Doe"
  },
  "message": {
    "id": "<task-id>",
    "title": "Follow up with Jane",
    "description": "Confirm pricing and send proposal",
    "type": "follow_up",
    "priority": "high",
    "stage": "<stage-id>",
    "due_date": "2026-01-20T15:00:00Z",
    "source": "ai",
    "source_detail": "<source-detail>",
    "campaign_id": "<campaign-id>",
    "linked_human_alert": "<human-alert-id>",
    "tags": ["qualified-lead"],
    "notes": "Customer requested a callback"
  }
}

Desativar (ou Eliminar) um Webhook #

Cada webhook tem um interruptor de ligar/desligar, diretamente na sua linha. Desligar um desativa a receção de eventos, mas mantém tudo o que configurou — o URL, os eventos, qualquer segredo de assinatura. Volte a ligá-lo e ele retoma de onde parou; nada do que aconteceu enquanto estava desligado será entregue posteriormente.

Utilize esta opção quando pretender interromper as entregas durante algum tempo: o seu endpoint está a ser reconstruído, está a depurar uma integração ruidosa ou a pausar uma automatização.

Eliminar um webhook (o ícone do caixote do lixo na sua linha) remove-o permanentemente, incluindo o seu segredo de assinatura. Se apenas pretende que as entregas parem, desligue-o em vez disso — a eliminação serve para quando já não precisa do endpoint.

Isto não é o mesmo que um webhook ser desligado automaticamente. Se desativarmos o seu webhook após falhas repetidas (consulte Fiabilidade de Webhooks), o interruptor acima não o voltará a ativar. Assim que o seu endpoint estiver corrigido, edite o webhook e guarde-o com um URL alterado (qualquer alteração de URL reativa-o), ou chame o endpoint de reativação através da API — ou peça ao suporte e nós reativá-lo-emos por si.

Payloads Assinados (Verificar se um Webhook veio realmente de nós) #

Qualquer pessoa que descubra o seu URL de webhook pode enviar-lhe um pedido falso. Se atua com base em webhooks automaticamente — atualizando faturação, criando registos de CRM — ativar a assinatura permite-lhe verificar se cada pedido veio genuinamente da nossa parte.

A assinatura é opcional e desativada por predefinição, e ativa-a por webhook, a partir da vista de edição desse webhook (abra a linha de um webhook guardado).

Ativar a assinatura #

1. Abra o webhook (Definições → Integrações → Webhooks → clique na linha do seu webhook).
2. Na secção Segredo de assinatura, clique em Gerar.
3. Copie o segredo (começa com whsec_) e guarde-o no seu sistema recetor. Trate-o como uma palavra-passe.

Pode voltar e revelar, copiar, rodar ou desativar o segredo a qualquer momento a partir deste mesmo painel.

O que enviamos #

Assim que a assinatura estiver ativa, cada entrega para esse webhook transporta estes dois cabeçalhos HTTP adicionais:

Estes três estão em todas as entregas, assinadas ou não:

Como verificar #

A assinatura é um HMAC-SHA256 da string <timestamp>.<raw request body>, utilizando o seu segredo de assinatura como chave.

Verifique contra o corpo do pedido bruto — os bytes exatos que recebeu. Se o seu framework analisar o JSON e o voltar a serializar antes de verificar, os bytes podem mudar e a assinatura não corresponderá.

Exemplo em Node.js:

const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const timestamp = headers["x-webhook-timestamp"];
  const signature = headers["x-webhook-signature"]; // "v1=<hex>"

  // Reject anything older than 5 minutes so a captured request can't be replayed later.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");

  return crypto.timingSafeEqual(Buffer.from(signature.replace("v1=", "")), Buffer.from(expected));
}

Exemplo em Python:

import hashlib, hmac, time

def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers["X-Webhook-Timestamp"]
    signature = headers["X-Webhook-Signature"].replace("v1=", "")

    # Reject anything older than 5 minutes so a captured request can't be replayed later.
    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256).hexdigest()

    return hmac.compare_digest(signature, expected)

Compare assinaturas com uma função segura contra ataques de temporização (timingSafeEqual / compare_digest), não ==. Não tem qualquer custo e evita uma classe subtil de ataques.

Rotação do segredo #

Clique em Rodar para substituir o segredo. A mudança é imediata: a entrega seguinte é assinada apenas com o novo segredo. Se o seu endpoint estiver ativo, aceite ambos os segredos (o antigo e o novo) durante alguns minutos enquanto implementa o novo.

Desativar a assinatura simplesmente impede o envio dos cabeçalhos de assinatura.

Repetição de Entregas Falhadas #

Por predefinição, uma entrega que falha não é repetida — se o seu sistema estiver em baixo nesse momento, esse evento é perdido.

Ative a opção Tentar novamente entregas falhadas num webhook (no formulário de criação/edição) e continuaremos a tentar:

Isso abrange cerca de 2 horas e 40 minutos, pelo que um webhook pode sobreviver a uma janela de manutenção ou a uma breve interrupção do seu lado.

O que é repetido: problemas temporários — o seu servidor a devolver um erro 5xx, um timeout ou uma falha de ligação.

O que não fazemos: se o seu endpoint rejeitar o pedido (qualquer erro 4xx), não tentamos novamente — enviar o mesmo pedido repetidamente apenas produziria a mesma rejeição.

Que eventos são reintentados: todos os eventos, desde 24 de setembro de 2026. Isto abrange webhooks de etiquetas (contact_tags_updated), os três eventos de tarefa, o resumo diário, o webhook de resumo, Nova Mensagem, Conversa Concluída, Contacto em Pausa, Contacto Retomado, Contacto Não Incomodar, Contacto Desarquivado, Saldo de Crédito Baixo, os eventos de Transmissão, e os eventos de contacto e atividade: Contacto Criado, Marcação Agendada, Humano Alertado, Respostas, Leituras, Entregas, Créditos Gastos e Créditos Recarregados. Antes dessa data, Nova Mensagem, Conversa Concluída, Contacto em Pausa, Contacto Retomado, Contacto Não Incomodar, Contacto Desarquivado e o webhook de resumo eram enviados uma vez, independentemente do interruptor. Cada evento transporta X-Webhook-Delivery, pelo que uma regra de desduplicação abrange todos eles.

Ative as tentativas de reenvio apenas se o seu endpoint for idempotente. As tentativas de reenvio significam que o mesmo evento pode chegar mais do que uma vez. Utilize o cabeçalho X-Webhook-Delivery para reconhecer uma repetição: este permanece igual em todas as tentativas para um evento, pelo que pode ignorar com segurança um ID que já tenha processado.

As tentativas de reenvio interagem com a desativação automática após falhas repetidas (consulte Fiabilidade do Webhook) da forma que pretende: o contador de falhas conta uma entrega completa, apenas após todas as tentativas de reenvio terem sido esgotadas — e não cada tentativa individual.

Fiabilidade do Webhook #

• O Your AI Connector envia webhooks através de uma ligação segura (HTTPS). Certifique-se de que o endereço web que fornece utiliza HTTPS.
• Se o seu sistema devolver um erro, a entrega é considerada falhada.
• Monitorize o tempo de atividade do seu sistema recetor para evitar perder eventos.
• Para fluxos de trabalho críticos, ative Tentar Novamente Entregas Falhadas e considere também um mecanismo de redundância.

Os webhooks são desligados automaticamente após falhas repetidas. Se o URL do seu webhook falhar repetidamente (cerca de 5 erros seguidos, ou 3 seguidos para erros de configuração), o Your AI Connector para automaticamente de enviar eventos para esse URL. Para o reativar assim que o seu endpoint estiver operacional: edite o webhook e guarde-o com um URL alterado (qualquer alteração de URL reativa-o), ou utilize o endpoint de reativação através da API — guardar novamente com o mesmo URL não é suficiente. O suporte também pode reativá-lo por si.

Resolução de Problemas #

Próximos Passos #

• Integração GoHighLevel — utilize webhooks para integrar o Your AI Connector com o GHL.
• Acesso à API — combine webhooks com a API para automatizações poderosas.
• Utilizar Etiquetas para Identificar Contactos — configure etiquetas que disparam os seus webhooks.