Webhooks
Um evento em um sistema ativa uma ação em outro
Webhook é uma maneira de um sistema enviar informações automaticamente para outro sistema sempre que algo importante acontece.
📖 Nossa plataforma oferece diversos webhooks que disparam conforme um evento interno, como envios de mensagens, mudanças de status, tags, etc permitindo integrações com outras aplicações.
Também temos os Webhook Triggers, que são os endpoints receptivos de Webhooks externos. Assim, é possível iniciar um fluxo de conversa quando uma aplicação externa envia um sinal para nosso sistema, como por exemplo uma notificação de um sistema de pagamento, cadastro de lead no site, e outros.
📌 Webhook de Conexão: Notificações em Tempo Real
Este webhook envia notificações com dados sempre que ocorrerem os seguintes eventos em uma CONEXÃO:
Receber uma mensagem
Enviar uma mensagem
Alterar uma tag no ticket
Alterar o status do ticket (abrir ou fechar)
Ao ocorrer um desses eventos, o webhook envia um payload (dados) para o seu endpoint (URL), notificando automaticamente o sistema receptor.
Como configurar o Endpoint (URL) do sistema receptor:
Configure seu receptor para receber nossas notificações através do método POST.
Copie a URL de destino do seu sistema receptor.
Acesse em nosso sistema o menu Conexões.
Selecione Editar Conexão.
No campo Webhook, adicione a URL copiada.
Pronto! Agora você poderá visualizar as notificações dos nossos webhooks chegando ao seu endpoint.
Payload Enviado
Um payload diferente é enviado para cada tipo de ação. Veja os exemplos abaixo:
1. Mensagens
JSON
{
"body": {
"filaescolhida": "Dep. Entregas",
"filaescolhidaid": 5,
"mensagem": "Mensagem de teste",
"sender": "5511999999999",
"chamadoId": 15321,
"acao": "start",
"name": "José Cliente",
"companyId": 8,
"defaultWhatsapp_x": 27,
"fromMe": false,
"queueId": 5,
"isGroup": false,
"ticketData": {
"id": 15321,
"status": "open",
"unreadMessages": 0,
"lastMessage": "Mensagem anterior ao de teste",
"protocolo": "54212",
"typebot_sessionId": null,
"typebot_status": null,
"customA": null,
"lastFlowId": null,
"repeatCount": 0,
"fromAds": 24,
"customB": null,
"nextFlowId": null,
"isGroup": false,
"userId": 71,
"contactId": 16991,
"whatsappId": 27,
"queueId": 5,
"chatbot": false,
"isMenu": false,
"variables": null,
"channel": "whatsapp",
"queueOptionId": null,
"companyId": 8,
"uuid": "9165510e-d4b0-1234-8aa4-222cc8b2344a",
"promptId": null,
"createdAt": "2024-12-21T14:06:31.404Z",
"updatedAt": "2025-03-21T17:45:00.575Z",
"contact": {
"id": 16991,
"name": "José Cliente",
"number": "5511999999999",
"email": "",
"acceptAudioMessage": true,
"active": true,
"disableBot": false,
"extraInfo": []
},
"user": {
"id": 71,
"name": "João Atendimento",
"restricted": false,
"away": false,
"ausencia": null,
"sigame": false,
"number": "5511987654321"
},
"queue": {
"id": 5,
"name": "Dep. Entregas",
"color": "#f44e3b",
"typeboturl": "",
"typebotname": "",
"typebotexpire": 5000,
"typebotwait": 1500,
"flowiseKey": "",
"flowiseUrl": "",
"promptId": null,
"invalidMessage": "",
"flowId": null,
"zaiaToken": "",
"zaiaAgent": null,
"isTranscribe": false,
"difyToken": null,
"difyURL": null,
"webhookQueueURL": null,
"prompt": null
},
"whatsapp": {
"name": "Atendimento",
"webhook": "https://go.dominio.com.br/webhook",
"id": 27,
"token": "7ydsa6dahdaksdas9",
"coverImage": null,
"selectedCommentQueueId": null,
"whatsmeowname": null,
"whatsmeowtoken": null,
"whatsmeowurl": null,
"hubtoken": null,
"channel": "whatsapp",
"status": "CONNECTED",
"ignoreNumbers": ""
},
"tags": [
{
"id": 27,
"name": "Atenção",
"color": "#CD0003",
"TicketTag": {
"ticketId": 52,
"tagId": 27,
"disparei": 0,
"createdAt": "2025-03-24T11:51:41.779Z",
"updatedAt": "2025-03-24T11:51:41.779Z"
}
}
],
"company": {
"name": "Atendimento - Minha Empresa"
}
},
"backendURL": "https://backend_url.com.br",
"token_origin": "7ydsa6dahdaksdas9",
"msg": {
"key": {
"remoteJid": "[email protected]",
"fromMe": false,
"id": "3EB46F40017BA9"
},
"message": {
"extendedTextMessage": {
"text": "Mensagem de teste"
}
},
"messageTimestamp": "1742906049",
"status": "PENDING"
}
},
"webhookUrl": "https://go.dominio.com.br/webhook",
"executionMode": "production"
}
Os tipos de mensagens dentro de "body" > "msg" > "message" podem ser:
conversation (via celular)
extendedTextMessage (via Web)
audioMessage
imageMessage
videoMessage
documentMessage
reactionMessage
stickerMessage
contactMessage
locationMessage
2. Tags
{
"body": {
"action": "tag-sync",
"tags": {
"ticketId": 15321,
"tags": [
{
"id": 71,
"name": "particular",
"color": "#E1A903",
"kanban": 0,
"prioridade": 0,
"automation": 0,
"flowsId": 0,
"conversao": null,
"tagType": "Atendimento",
"companyId": 8,
"createdAt": "2025-03-15T18:56:21.655Z",
"updatedAt": "2025-03-15T18:56:21.655Z"
}
]
},
"contact": {
"id": 16991,
"name": "José Cliente",
"number": "5511999999999",
"email": "",
"acceptAudioMessage": true,
"active": true,
"disableBot": false,
"extraInfo": []
},
"connection_token": "7ydsa6dahdaksdas9",
"apiUrl": "https://backend_url.com.br"
},
"webhookUrl": "https://go.dominio.com.br/webhook",
"executionMode": "production"
}
3. Abrir ou Fechar Ticket
JSON
{
"body": {
"sender": "5511999999999",
"chamadoId": 20956,
"acao": "open",
"companyId": 1,
"defaultWhatsapp_x": 1,
"queueId": 16,
"isGroup": false,
"backendURL": "https://backend_url.com.br",
"ticketData": {
"id": 20956,
"status": "pending",
"unreadMessages": 1,
"lastMessage": "olá, tudo bem?",
"protocolo": "29924",
"typebot_sessionId": null,
"typebot_status": null,
"customA": null,
"lastFlowId": "SXG8YYNS5OWesf2oFYvLB89K2ETTeY",
"repeatCount": 0,
"fromAds": 24,
"customB": null,
"nextFlowId": null,
"isGroup": false,
"userId": null,
"contactId": 21019,
"whatsappId": 1,
"queueId": 16,
"chatbot": false,
"isMenu": false,
"variables": null,
"channel": "whatsapp",
"queueOptionId": null,
"companyId": 1,
"uuid": "872b49d0-c009-1234-b640-1c558b69d5bd",
"promptId": null,
"createdAt": "2025-03-25T15:41:55.115Z",
"updatedAt": "2025-03-25T18:43:47.366Z",
"contact": {
"id": 16991,
"name": "José Cliente",
"number": "5511999999999",
"email": "",
"acceptAudioMessage": true,
"active": true,
"disableBot": false,
"extraInfo": []
},
"queue": {
"id": 16,
"name": "Dep. Orçamentos",
"color": "#999999",
"typeboturl": "",
"typebotname": "",
"typebotexpire": 5000,
"typebotwait": 1500,
"flowiseKey": "",
"flowiseUrl": "",
"promptId": null,
"invalidMessage": "",
"flowId": null,
"zaiaToken": "",
"zaiaAgent": null,
"isTranscribe": false,
"difyToken": null,
"difyURL": null,
"webhookQueueURL": null,
"prompt": null
},
"whatsapp": {
"name": "Atendimento",
"webhook": "https://go.dominio.com.br/webhook",
"id": 27,
"token": "7ydsa6dahdaksdas9",
"coverImage": null,
"selectedCommentQueueId": null,
"whatsmeowname": null,
"whatsmeowtoken": null,
"whatsmeowurl": null,
"hubtoken": null,
"channel": "whatsapp",
"status": "CONNECTED",
"ignoreNumbers": ""
},
"tags": [],
"company": {
"name": "Atendimento - Minha Empresa"
}
}
},
"webhookUrl": "https://go.dominio.com.br/webhook",
"executionMode": "production"
}
4. Envio de Áudio, Imagem ou Arquivo
O envio de áudio, imagem ou arquivo no WhatsApp gera o envio de dois webhooks sequenciais.
O primeiro webhook é similar ao de "mensagem", porém a propriedade "mensagem" conterá:
"mensagem": "Áudio" (se for um áudio)
"mensagem": "" (se for uma imagem ou vídeo)
"mensagem": "nome do arquivo" (se for um arquivo PDF)
Na sequência, o segundo webhook será recebido com o seguinte payload:
JSON
{
"body": {
"sender": "5511999999999",
"chamadoId": 20956,
"acao": "fila-data",
"companyId": 1,
"defaultWhatsapp_x": 1,
"fromMe": false,
"queueId": 16,
"isGroup": false,
"ticketData": {
"id": null,
"status": null,
"unreadMessages": null,
"lastMessage": null,
"protocolo": null,
"typebot_sessionId": null,
"typebot_status": null,
"customA": null,
"lastFlowId": null,
"repeatCount": null,
"fromAds": null,
"customB": null,
"nextFlowId": null,
"isGroup": null,
"userId": null,
"contactId": null,
"whatsappId": null,
"queueId": null,
"chatbot": null,
"isMenu": null,
"variables": null,
"channel": null,
"queueOptionId": null,
"companyId": null,
"uuid": null,
"promptId": null,
"createdAt": null,
"updatedAt": null,
"contact": {
"id": null,
"name": null,
"number": null,
"email": null,
"profilePicUrl": null,
"acceptAudioMessage": null,
"active": null,
"disableBot": null,
"extraInfo": []
},
"user": null,
"queue": {
"id": null,
"name": null,
"color": null,
"typeboturl": null,
"typebotname": null,
"typebotexpire": null,
"typebotwait": null,
"flowiseKey": null,
"flowiseUrl": null,
"promptId": null,
"invalidMessage": null,
"flowId": null,
"zaiaToken": null,
"zaiaAgent": null,
"isTranscribe": null,
"difyToken": null,
"difyURL": null,
"webhookQueueURL": null,
"prompt": null
},
"whatsapp": {
"name": null,
"webhook": null,
"id": null,
"token": null,
"coverImage": null,
"selectedCommentQueueId": null,
"whatsmeowname": null,
"whatsmeowtoken": null,
"whatsmeowurl": null,
"hubtoken": null,
"channel": null,
"status": null,
"ignoreNumbers": null
},
"tags": [],
"company": {
"name": null
}
},
"mediaFolder": "public/company1",
"mediaName": "1742984582802.ogg",
"backendURL": "https://backend_url.com.br",
"token_origin": "7ydsa6dahdaksdas9",
"msg": {
"key": {
"remoteJid": null,
"fromMe": null,
"id": null
},
"message": null,
"messageTimestamp": null,
"status": null
}
},
"webhookUrl": "https://go.dominio.com.br/webhook",
"executionMode": "production"
}
📌 Webhook de Filas: Notificações Específicas por Fila
Nosso Webhook de Filas envia notificações com dados sempre que ocorrerem os seguintes eventos em um ticket pertencente a uma FILA:
Receber uma mensagem
Enviar uma mensagem
Alterar uma tag no ticket
Alterar o status do ticket (abrir ou fechar)
Sempre que um desses eventos ocorre em um ticket pertencente a essa fila, nosso webhook envia um payload (dados) para o seu endpoint (URL), notificando automaticamente o sistema receptor.
Importante!
Se o webhook de conexão e o de filas estiverem ativos ao mesmo tempo:
Quando o lead não estiver na fila selecionada: somente o webhook de conexão será disparado.
Quando o lead estiver na fila selecionada: os dois webhooks serão disparados.
Como configurar o Endpoint (URL) do sistema receptor:
Configure seu receptor para receber nossas notificações através do método POST.
Copie a URL de destino do seu sistema receptor.
Acesse em nosso sistema o menu Filas & Chatbot.
Selecione Editar Fila.
No campo Url do Webhook, adicione a URL copiada.
Pronto! Agora você poderá visualizar as notificações dos nossos webhooks chegando ao seu endpoint.
Payload Enviado
Um payload diferente é enviado para cada tipo de ação. Veja os exemplos abaixo:
1. Mensagens
JSON
{
"body": {
"filaescolhida": "Dep. Entregas",
"filaescolhidaid": 5,
"mensagem": "Mensagem de teste",
"sender": "5511999999999",
"chamadoId": 15321,
"acao": "start",
"name": "José Cliente", // se recebida = nome do cliente | se enviada = cel do cliente (5511999999999)
"companyId": 8,
"defaultWhatsapp_x": 27,
"fromMe": false, // se recebida = false | se enviada = true
"queueId": 5,
"isGroup": false,
"ticketData": {
"id": 15321,
"status": "open",
"unreadMessages": 0,
"lastMessage": "Mensagem anterior ao de teste", // se recebida = mensagem anterior | se enviada = mensagem atual
"protocolo": "54212",
"typebot_sessionId": null,
"typebot_status": null,
"customA": null,
"lastFlowId": null,
"repeatCount": 0,
"fromAds": 24,
"customB": null,
"nextFlowId": null,
"isGroup": false,
"userId": 71,
"contactId": 16991,
"whatsappId": 27,
"queueId": 5,
"chatbot": false,
"isMenu": false,
"variables": null,
"channel": "whatsapp",
"queueOptionId": null,
"companyId": 8,
"uuid": "9165510e-d4b0-1234-8aa4-222cc8b2344a",
"promptId": null,
"createdAt": "2024-12-21T14:06:31.404Z",
"updatedAt": "2025-03-21T17:45:00.575Z",
"contact": {
"id": 16991,
"name": "José Cliente",
"number": "5511999999999",
"email": "",
"profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/3653963772_n.jpg?stp=dst-jpg_s96x96_tt6&ccb=11-4&oh=01_Q5AaIWagepE1pi1UEjOTUa4Mf9hyz3bicAoUUMmu068SRl93&oe=67E90699&_nc_sid=5e03e0&_nc_cat=111",
"acceptAudioMessage": true,
"active": true,
"disableBot": false,
"extraInfo": []
},
"user": {
"id": 71,
"name": "João Atendimento",
"restricted": false,
"away": false,
"ausencia": null,
"sigame": false,
"number": "5511987654321"
},
"queue":
{
"id": 5,
"name": "Dep. Entregas",
"color": "#f44e3b",
"typeboturl": "",
"typebotname": "",
"typebotexpire": 5000,
"typebotwait": 1500,
"flowiseKey": "",
"flowiseUrl": "",
"promptId": null,
"invalidMessage": "",
"flowId": null,
"zaiaToken": "",
"zaiaAgent": null,
"isTranscribe": false,
"difyToken": null,
"difyURL": null,
"webhookQueueURL": null,
"prompt": null
},
"whatsapp": {
"name": "Atendimento",
"webhook": "https://go.dominio.com.br/webhook",
"id": 27,
"token": "7ydsa6dahdaksdas9",
"coverImage": null,
"selectedCommentQueueId": null,
"whatsmeowname": null,
"whatsmeowtoken": null,
"whatsmeowurl": null,
"hubtoken": null,
"channel": "whatsapp",
"status": "CONNECTED",
"ignoreNumbers": ""
},
"tags": [
{
"id": 27,
"name": "Atenção",
"color": "#CD0003",
"TicketTag": {
"ticketId": 52,
"tagId": 27,
"disparei": 0,
"createdAt": "2025-03-24T11:51:41.779Z",
"updatedAt": "2025-03-24T11:51:41.779Z"
}
}
],
"company": {
"name": "Atendimento - Minha Empresa"
}
},
"backendURL": "https://backend_url.com.br",
"token_origin": "7ydsa6dahdaksdas9",
"msg": {
"key": {
"remoteJid": "[email protected]",
"fromMe": false,
"id": "3EB46F40017BA9"
},
"message": {
"extendedTextMessage": {
"text": "Mensagem de teste"
}
}
"messageTimestamp": "1742906049",
"status": "PENDING"
}
},
"webhookUrl": "https://go.dominio.com.br/webhook",
"executionMode": "production"}
Os tipos de mensagens dentro de "body" > "msg" > "message" podem ser:
conversation (via celular)
extendedTextMessage (via Web)
audioMessage
imageMessage
videoMessage
documentMessage
reactionMessage
stickerMessage
contactMessage
locationMessage
2. Tags
JSON
{
"body": {
"action": "tag-sync",
"tags": {
"ticketId": 15321,
"tags": [
{
"id": 71,
"name": "particular",
"color": "#E1A903",
"kanban": 0,
"prioridade": 0,
"automation": 0,
"flowsId": 0,
"conversao": null,
"tagType": "Atendimento",
"companyId": 8,
"createdAt": "2025-03-15T18:56:21.655Z",
"updatedAt": "2025-03-15T18:56:21.655Z"
}
]
},
"contact": {
"id": 16991,
"name": "José Cliente",
"number": "5511999999999",
"email": "",
"profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/44599_56578365129263772_n.jpg?stp=dst-jpg_s96x96_tt6&ccb=11-4&oh=01_Q5AaIdaAniZV10jFWDbcoIOlKodMuWHQeZ4C2DV-gJQxQtFx&oe=67E236D9&_nc_sid=5e03e0&_nc_cat=111",
"acceptAudioMessage": true,
"active": true,
"disableBot": false,
"extraInfo": []
},
"connection_token": "7ydsa6dahdaksdas9",
"apiUrl": "https://backend_url.com.br
},
"webhookUrl": "https://go.dominio.com.br/webhook",
"executionMode": "production"}
3. Abrir ou Fechar Ticket
JSON
{
"body": {
"sender": "5511999999999",
"chamadoId": 20956,
"acao": "open", // closed = se for encerramento de ticket
"companyId": 1,
"defaultWhatsapp_x": 1,
"queueId": 16,
"isGroup": false,
"backendURL": "https://backend_url.com.br",
"ticketData": {
"id": 20956,
"status": "pending",
"unreadMessages": 1,
"lastMessage": "olá, tudo bem?",
"protocolo": "29924",
"typebot_sessionId": null,
"typebot_status": null,
"customA": null,
"lastFlowId": "SXG8YYNS5OWesf2oFYvLB89K2ETTeY",
"repeatCount": 0,
"fromAds": 24,
"customB": null,
"nextFlowId": null,
"isGroup": false,
"userId": null,
"contactId": 21019,
"whatsappId": 1,
"queueId": 16,
"chatbot": false,
"isMenu": false,
"variables": null,
"channel": "whatsapp",
"queueOptionId": null,
"companyId": 1,
"uuid": "872b49d0-c009-1234-b640-1c558b69d5bd",
"promptId": null,
"createdAt": "2025-03-25T15:41:55.115Z",
"updatedAt": "2025-03-25T18:43:47.366Z",
"contact": {
"id": 16991,
"name": "José Cliente",
"number": "5511999999999",
"email": "",
"profilePicUrl": "https://pps.whatsapp.net/v/t61.24694-24/3653963772_n.jpg?stp=dst-jpg_s96x96_tt6&ccb=11-4&oh=01_Q5AaIWagepE1pi1UEjOTUa4Mf9hyz3bicAoUUMmu068SRl93&oe=67E90699&_nc_sid=5e03e0&_nc_cat=111",
"acceptAudioMessage": true,
"active": true,
"disableBot": false,
"extraInfo": []
},
"queue": {
"id": 16,
"name": "Dep. Orçamentos",
"color": "#999999",
"typeboturl": "",
"typebotname": "",
"typebotexpire": 5000,
"typebotwait": 1500,
"flowiseKey": "",
"flowiseUrl": "",
"promptId": null,
"invalidMessage": "",
"flowId": null,
"zaiaToken": "",
"zaiaAgent": null,
"isTranscribe": false,
"difyToken": null,
"difyURL": null,
"webhookQueueURL": null,
"prompt": null
},
"whatsapp": {
"name": "Atendimento",
"webhook": "https://go.dominio.com.br/webhook",
"id": 27,
"token": "7ydsa6dahdaksdas9",
"coverImage": null,
"selectedCommentQueueId": null,
"whatsmeowname": null,
"whatsmeowtoken": null,
"whatsmeowurl": null,
"hubtoken": null,
"channel": "whatsapp",
"status": "CONNECTED",
"ignoreNumbers": ""
},
"tags": [],
"company": {
"name": "Atendimento - Minha Empresa"
}
}
},
"webhookUrl": "https://go.dominio.com.br/webhook",
"executionMode": "production"}
4. Envio de Áudio, Imagem ou Arquivo
O envio de áudio, imagem ou arquivo no WhatsApp gera o envio de dois webhooks sequenciais.
O primeiro webhook é similar ao de "mensagem", porém a propriedade "mensagem" conterá:
"mensagem": "Áudio" (se for um áudio)
"mensagem": "" (se for uma imagem ou vídeo)
"mensagem": "nome do arquivo" (se for um arquivo PDF)
Na sequência, o segundo webhook será recebido com o seguinte payload:
JSON
{
"body": {
"sender": "5511999999999",
"chamadoId": 20956,
"acao": "fila-data",
"companyId": 1,
"defaultWhatsapp_x": 1,
"fromMe": false,
"queueId": 16,
"isGroup": false,
"ticketData": { ... igual de mensagem ... },
"mediaFolder": "public/company1",
"mediaName": "1742984582802.ogg",
"backendURL": "https://backend_url.com.br",
"token_origin": "7ydsa6dahdaksdas9",
"msg": { ... igual de mensagem ... }
},
"webhookUrl": "https://go.dominio.com.br/webhook",
"executionMode": "production"}
📌 Webhook Triggers
Com o nosso Webhook Triggers, você pode configurar um webhook de um sistema externo para notificar o nosso sistema quando ocorrer um evento e, assim, iniciar um fluxo no nosso Flowbuilder.
Tudo em 3 passos
algo acontece em um sistema externo: recebimento de um pagamento, entrada de um lead, etc.
sistema externo notifica o nosso sistema: via webhook deles, apontando para um dos nossos endpoints do Webhook Triggers.
inicia um fluxo no Flowbuilder: conforme configurado nesse endpoint do Webhook Trigger
Como configurar o Endpoint (URL) em nosso sistema
Acesse, em nosso sistema, o menu Webhook | Triggers+ Novo Webhook | Triggers e no campo Webhook adicione a URL copiada.
✅Pronto.
Agora acesse o ícone de “ferramenta” desse Webhook Trigger para configurá-lo.
Copie a URL do seu endpoint
E coloque-a na URL do Webhook do sistema externo.
Ajuste o payload do seu Webhook externo
Para enviar via POST dados em formato JSON, sendo obrigatório o envio de “nome”, “celular” e “email”. Envie campos extras se precisar.
Atualizar Dados no webhook trigger
Faça o webhook externo disparar uma notificação em seu endpoint do Webhook Trigger, e então clique no botão “Atualizar Dados“.
O payload enviado pelo wehook externo vai aparecer no campo de última requisição que este webhook recebeu.
Agora você consegue …
Setar as Variáveis
Em cada campo defina o valor das variáveis. Elas serão acessadas no fluxo utilizando %celular%, %nome%, %email%, %extra1% …
Defina Fluxo e Conexão
Por fim defina qual fluxo do webhook iniciará quando o webhook trigger receber o sinal. (lembre-se, você deve selecionar a fila que tem o fluxo vinculado)
E escolha qual conexão será remetente nesse fluxo.
✅ Salvar Webhook.
Como usar as Variáveis no fluxo
Utilize %celular%, %nome%, %email%, %extra1%, etc …
