Webhooks
Webhooks permitem que um sistema externo receba eventos da Agilize sem precisar consultar a API continuamente.
Antes de configurar
- Crie uma URL pública HTTPS para receber eventos.
- Garanta que o endpoint responda rapidamente.
- Registre logs suficientes para investigar falhas.
- Valide o formato do payload antes de processar regras de negócio.
Eventos disponíveis
A lista abaixo é carregada automaticamente a partir do Swagger oficial da Agilize. Quando a API oficial não estiver disponível, a documentação usa a última versão local de fallback.
Eventos do Swagger
Webhooks disponíveis
Arquivos - Upload
3 eventosPOSTDocumento - Criaçãofile/upload/create
mimetypestring namestring sizenumber categorystring md5string isTempboolean canDeleteboolean canDeleteLocalboolean localDeleteAfterstring:date-time extStorageboolean POSTDocumento - Atualizaçãofile/upload/patch
mimetypestring namestring sizenumber categorystring md5string isTempboolean canDeleteboolean canDeleteLocalboolean localDeleteAfterstring:date-time extStorageboolean POSTDocumento - Exclusãofile/upload/remove
_idstring Identificador do registro excluído
CRM - Oportunidades
9 eventosPOSTFunil - Criaçãocrm/lead/funnel/create
namestring stagesobject[] deletedboolean validatePreviousStageRequirementsboolean allowArchiveWithoutRequiredFieldsboolean disableDefaultWonLossStagesboolean hideWonKanbanboolean hideArchivedKanbanboolean POSTFunil - Atualizaçãocrm/lead/funnel/patch
namestring stagesobject[] deletedboolean validatePreviousStageRequirementsboolean allowArchiveWithoutRequiredFieldsboolean disableDefaultWonLossStagesboolean hideWonKanbanboolean hideArchivedKanbanboolean POSTFunil - Exclusãocrm/lead/funnel/remove
_idstring Identificador do registro excluído
POSTOportunidade - Criaçãocrm/lead/lead/create
contactsstring[] automationsstring[] companiesstring[] phonesobject[] emailsobject[] socialsobject[] namestring Nome descritivo
userstring createdBystring importstring Id da importação, caso tenha sido importado
POSTOportunidade - Atualizaçãocrm/lead/lead/patch
contactsstring[] automationsstring[] companiesstring[] phonesobject[] emailsobject[] socialsobject[] namestring Nome descritivo
userstring createdBystring importstring Id da importação, caso tenha sido importado
POSTOportunidade - Exclusãocrm/lead/lead/remove
_idstring Identificador do registro excluído
POSTOrigem de oportunidade - Criaçãocrm/lead/source/create
namestring colorstring POSTOrigem de oportunidade - Atualizaçãocrm/lead/source/patch
namestring colorstring POSTOrigem de oportunidade - Exclusãocrm/lead/source/remove
_idstring Identificador do registro excluído
CRM - Suporte
3 eventosPOSTSuporte - Criaçãocrm/support/support/create
customerstring Cliente do CRM associado ao ticket quando a operacao usar vinculo formal de customer.
roomstring Sala de conversa de origem do ticket. Usada para vinculo operacional com o Messenger.
contactstring Contato principal relacionado ao ticket.
numbernumber Numero sequencial do ticket dentro do projeto.
subjectstring Assunto curto do ticket exibido em listagens, cards e cabecalho do atendimento.
categorystring Categoria principal do ticket.
subCategorystring Subcategoria do ticket. Quando informada, a categoria pai pode ser resolvida automaticamente.
departmentstring Departamento do Messenger vinculado ao contexto do ticket, quando houver origem por sala.
teamstring Equipe CRM responsavel pela fila e distribuicao do ticket.
userstring Usuario responsavel pelo ticket. Pode ser definido manualmente ou por distribuicao automatica.
POSTSuporte - Atualizaçãocrm/support/support/patch
customerstring Cliente do CRM associado ao ticket quando a operacao usar vinculo formal de customer.
roomstring Sala de conversa de origem do ticket. Usada para vinculo operacional com o Messenger.
contactstring Contato principal relacionado ao ticket.
numbernumber Numero sequencial do ticket dentro do projeto.
subjectstring Assunto curto do ticket exibido em listagens, cards e cabecalho do atendimento.
categorystring Categoria principal do ticket.
subCategorystring Subcategoria do ticket. Quando informada, a categoria pai pode ser resolvida automaticamente.
departmentstring Departamento do Messenger vinculado ao contexto do ticket, quando houver origem por sala.
teamstring Equipe CRM responsavel pela fila e distribuicao do ticket.
userstring Usuario responsavel pelo ticket. Pode ser definido manualmente ou por distribuicao automatica.
POSTSuporte - Exclusãocrm/support/support/remove
_idstring Identificador do registro excluído
Mensagens - Chat
3 eventosPOSTSala de Conversa - Criaçãomessenger/chat/room/create
gueststring usersstring[] prefUserstring ownerstring prefUserPendAttrboolean histUsersstring[] tagsstring[] conversationDetailTagsstring[] departmentstring Departamento atual da sala
contactstring POSTSala de Conversa - Atualizaçãomessenger/chat/room/patch
gueststring usersstring[] prefUserstring ownerstring prefUserPendAttrboolean histUsersstring[] tagsstring[] conversationDetailTagsstring[] departmentstring Departamento atual da sala
contactstring POSTSala de Conversa - Exclusãomessenger/chat/room/remove
_idstring Identificador do registro excluído
Mensagens - Chatbot
2 eventosPOSTControle Fluxo de Chatbot Webhookmessenger/chatbot/NodeHttpDelegate
Metodo HTTP chamado pelo node Requisicao HTTP (Delegar) durante a execucao do fluxo de chatbot. O endpoint externo recebe a mensagem atual, os dados do canal e o objeto vars com as variaveis ja persistidas no contexto do fluxo. O retorno deve ser um JSON com: - messages: mensagens que a plataforma deve enviar ao contato. - keepHere: true para manter a conversa neste endpoint e aguardar nova mensagem; false para avancar para a saida do node. - vars: objeto com todas as variaveis que precisam ser salvas no contexto do fluxo antes de avancar. Importante: somente campos dentro de vars sao persistidos e ficam disponiveis para os proximos nodes. Campos retornados no topo do JSON nao sao usados por nodes que leem variaveis nem por templates. Exemplo: se o proximo node avalia uma variavel de decisao, retorne essa chave dentro de vars. Se um node usa templates como {{nome}}, {{produto}} ou {{observacao}}, esses campos tambem devem ser retornados dentro de vars.
seqinteger obrigatórioSequência da mensagem no fluxo atual
roomIdstring ID da sala de conversa atual
chIdstring Identificador do contato no canal
chSrcinteger Canal de origem (1=WhatsApp, 2=Facebook, 3=Instagram, 4=SMS; ausência/valor diferente indica LiveChat)
message[
"string",
"null"
] Texto enviado pelo contato na mensagem atual, quando houver
varsobject obrigatórioVariáveis já persistidas no contexto do fluxo. O endpoint pode usar esses valores para decidir a resposta e deve retornar novas variáveis em response.vars.
interactiveReplystring Resposta interativa do usuário
currNodeIdstring ID do node atual no fluxo
POSTWebhook HTTP (Saída) do Chatbotmessenger/chatbot/NodeHttpWebhook
Estrutura enviada pelo node NodeHttpWebhook para a URL configurada no fluxo. Este endpoint deve ser implementado pelo cliente/terceiro para receber os dados e reagir conforme necessário.
roomIdstring obrigatórioID da sala (room) no banco
chIdstring obrigatórioIdentificador do canal. No WhatsApp (chSrc=1) é o número do cliente.
chSrcinteger obrigatórioCanal de origem (1=WhatsApp, 2=Facebook, 3=Instagram, 4=SMS)
message[
"string",
"null"
] Texto da mensagem atual (quando houver)
interactiveReply[
"string",
"null"
] Resposta interativa do usuário (payload/id) quando aplicável
currNodeIdstring obrigatórioID do node atual no fluxo
varsobject obrigatórioVariáveis persistidas no contexto do fluxo (roomData.vars)
mediaobject Mídia/arquivo quando a mensagem contém anexo
_waReferralobject Referral do WhatsApp quando o webhook de mensagem veio com message.referral
Voz - PBX
4 eventosPOSTChamada - Vinculaçãovoice/pbx/call/link
channelstring obrigatórioIdentificador do canal da ligação
uniqueidstring obrigatórioId da Chamada (Origem)
subeventstring Definição do sub-evento.
dialstatusstring Status atual da chamada
destuniqueidstring Id da chamada na conexão de destino
calleridnumstring Número da Bina (Canal Origem)
calleridnamestring Nome da Bina (Canal Origem)
connectedlinenumstring Nome da Bina (Canal Conectado)
connectedlinenamestring Número da Bina (Canal Conectado)
dialstringstring Comando de discagem da central
POSTChamada - Desvinculaçãovoice/pbx/call/unlink
channelstring obrigatórioIdentificador do canal da ligação
uniqueidstring obrigatórioId da Chamada (Origem)
subeventstring Definição do sub-evento.
dialstatusstring Status atual da chamada
destuniqueidstring Id da chamada na conexão de destino
calleridnumstring Número da Bina (Canal Origem)
calleridnamestring Nome da Bina (Canal Origem)
connectedlinenumstring Nome da Bina (Canal Conectado)
connectedlinenamestring Número da Bina (Canal Conectado)
dialstringstring Comando de discagem da central
POSTCanal - Discagemvoice/pbx/channel/dial
channelstring obrigatórioIdentificador do canal da ligação
uniqueidstring obrigatórioId da Chamada (Origem)
subeventstring Definição do sub-evento.
dialstatusstring Status atual da chamada
calleridnumstring Número da Bina (Canal Origem)
calleridnamestring Nome da Bina (Canal Origem)
connectedlinenumstring Nome da Bina (Canal Conectado)
connectedlinenamestring Número da Bina (Canal Conectado)
pbxstring Identificador do canal da ligação
eventNamestring Nome completo do evento
POSTCanal - Encerramentovoice/pbx/channel/hangup
channelstring obrigatórioIdentificador do canal da ligação
uniqueidstring obrigatórioId da Chamada (Origem)
calleridnumstring Número da Bina (Canal Origem)
calleridnamestring Nome da Bina (Canal Origem)
connectedlinenumstring Nome da Bina (Canal Conectado)
connectedlinenamestring Número da Bina (Canal Conectado)
causeint Códigos de causa para o evento Hangup. Consulte <a href='https://www.voip-info.org/asterisk-cmd-hangup/' target='_blank'>esta página</a> para obter mais detalhes.
cause_txtstring Descrição
pbxstring Identificar/dóminio do seu PABX
eventNamestring Nome completo do evento
Boas práticas
- Responda com status de sucesso apenas depois de receber o evento corretamente.
- Trate reenvios como possibilidade real.
- Não dependa de uma única tentativa para executar uma ação crítica.