Como configurar webhooks de mensagens do Zendesk: Um guia completo

Webhooks transformam seu Zendesk em um motor de notificações em tempo real. Em vez de verificar manualmente se há atualizações, os webhooks enviam dados para sistemas externos no momento em que algo acontece, seja a criação de um ticket, a chegada de uma mensagem ou a atualização do perfil de um usuário.

As aplicações práticas variam desde alertas no Slack para tickets urgentes até a alimentação de ferramentas de IA como o eesel AI com dados de clientes ao vivo. Este guia percorre os dois tipos de webhooks do Zendesk (baseados em eventos e baseados em gatilhos), aborda a configuração específica de mensagens via Conversations API e explica os métodos de autenticação para que suas integrações permaneçam seguras.

Ao final, você terá webhooks funcionais conectados aos seus fluxos de trabalho de suporte.

O que são webhooks do Zendesk e como eles funcionam?

Um webhook envia uma solicitação HTTP para um URL especificado sempre que algo acontece no Zendesk Support, Guide, Gather ou Messaging. Pense nisso como uma notificação push em tempo real para seus sistemas. Quando um usuário é excluído ou um novo ticket chega, o Zendesk notifica seu endpoint com os dados relevantes.

Casos de uso comuns incluem:

• Alertas no Slack ou Teams para tickets de alta prioridade
• Sincronização de CRM para manter os registros dos clientes atualizados
• Notificações por SMS via serviços como Twilio ou 8x8
• Integrações de IA onde ferramentas processam mensagens recebidas e geram respostas

Dois métodos de conexão de webhook

Essa distinção é importante porque você não pode misturá-los. Depois de criar um webhook com um método, você não pode alterá-lo.

Webhooks de assinatura de eventos respondem a eventos do Zendesk, como criação de usuário, atualizações de organização, publicação de artigos na central de ajuda ou atividade de mensagens. Eles sempre usam POST com um payload JSON, e o Zendesk controla a estrutura do payload.

Webhooks de gatilho ou automação conectam-se às suas regras de negócios do Support. Quando um ticket atende a certas condições, o webhook é disparado. Você tem controle total sobre o método HTTP (GET, POST, PUT, PATCH, DELETE) e pode personalizar o formato da solicitação (JSON, XML ou codificado em formulário). O payload usa marcadores como {{ticket.id}} que o Zendesk preenche em tempo de execução.

Tipo de Conexão	Acionado Por	Métodos HTTP	Controle de Payload
Eventos do Zendesk	Atividade de usuário, org, mensagens, central de ajuda	Apenas POST	Definido pelo Zendesk
Gatilho/Automação	Condições do ticket	Todos os métodos	Definido pelo usuário com marcadores

Como configurar webhooks do Zendesk para mensagens e gatilhos

A configuração de webhooks requer acesso de administrador ou uma função personalizada com permissões de webhook. Aqui está o processo passo a passo.

Passo 1: Acesse a seção de webhooks na Central de Administração

Navegue até a Central de Administração e clique em Apps e integrações na barra lateral. Selecione Webhooks no submenu. Você verá uma lista de webhooks existentes (se houver) e um botão para criar novos.

Contas de teste têm limites: no máximo 10 webhooks e 60 invocações por minuto. Planos pagos removem essas restrições.

Passo 2: Crie um novo webhook

Clique em "Criar webhook" e escolha seu método de conexão:

• Eventos do Zendesk: Selecione esta opção para atividades de mensagens, usuário, organização ou central de ajuda. Você escolherá eventos específicos para assinar.
• Gatilho ou Automação: Selecione esta opção para atividades baseadas em tickets onde você deseja payloads personalizados.

A escolha aqui é permanente. Você não pode converter um webhook de gatilho em um webhook de assinatura de evento mais tarde, então escolha o correto desde o início.

Passo 3: Defina as configurações do webhook

Preencha a configuração básica:

• Nome e Descrição: Use nomes descritivos como "Alertas de tickets urgentes no Slack" ou "Sincronização de clientes no CRM" para que sua equipe saiba o que cada webhook faz.
• URL do endpoint: O URL do seu servidor de recebimento. HTTPS é fortemente recomendado por segurança.
• Método de solicitação: Para webhooks de assinatura de eventos, este é sempre POST. Para webhooks de gatilho, escolha com base no que seu endpoint espera.
• Formato da solicitação: JSON, XML ou codificado em formulário (apenas webhooks de gatilho).

Você também pode adicionar até 5 cabeçalhos personalizados para endpoints HTTPS. Os nomes dos cabeçalhos suportam caracteres alfanuméricos e alguns símbolos, com um limite de 128 caracteres. Os valores podem ter até 1.000 caracteres.

Passo 4: Configure a autenticação

Escolha o método de autenticação que seu endpoint exige:

Método	Quando Usar	Configuração
Nenhum	Testes ou endpoints com lista de permissões de IP	Nenhuma credencial necessária
Chave de API	Serviços de terceiros com autenticação de cabeçalho	Par nome/valor no cabeçalho
Autenticação Básica	Serviços internos ou chamadas de API do Zendesk	Nome de usuário e senha (use o formato {email}/token:{api_token} para o Zendesk)
Token de Portador	Serviços habilitados para OAuth	Token de acesso no cabeçalho de Autorização

Todos os métodos de autenticação devem usar HTTPS. Nunca coloque credenciais confidenciais em cabeçalhos personalizados — use as opções de autenticação integradas.

Passo 5: Conecte a um gatilho ou automação

Para webhooks baseados em gatilhos, você precisa conectá-los a uma regra de negócio:

1. Vá para a Central de Administração, depois Objetos e regras, depois Regras de negócios, depois Gatilhos.
2. Crie um novo gatilho ou edite um existente.
3. Em Ações, clique em "Adicionar ação".
4. Selecione "Notificar webhook" e escolha seu webhook no menu suspenso.
5. Defina o payload JSON usando marcadores (placeholders). Por exemplo:

{
  "ticket_id": "{{ticket.id}}",
  "subject": "{{ticket.title}}",
  "status": "{{ticket.status}}",
  "requester_email": "{{ticket.requester.email}}"
}

O Zendesk substitui esses marcadores pelos valores reais antes de enviar a solicitação. O payload deve ter menos de 256 KB.

Passo 6: Teste seu webhook

Antes de entrar em produção, use o recurso de teste integrado:

1. Abra seu webhook na página de Webhooks.
2. Clique em "Testar webhook".
3. Selecione um evento de amostra ou insira dados de teste.
4. Clique em "Enviar teste" e verifique a resposta.

Um código de status 200 significa sucesso. Se você receber erros, verifique os logs do seu endpoint. Problemas comuns incluem URLs errados, autenticação inválida ou payloads malformados.

Para desenvolvimento local, ferramentas como ngrok ou Hookdeck criam URLs públicos que fazem o túnel para seu servidor local. Isso permite que você teste webhooks sem implantar em produção.

Configurando webhooks de mensagens do Zendesk com a Conversations API

A plataforma de mensagens do Zendesk (Sunshine Conversations) possui seu próprio sistema de webhooks para mensagens em tempo real. Isso é separado dos webhooks padrão e projetado especificamente para interações de chat.

Criando um webhook de mensagens

Webhooks de mensagens pertencem a uma integração. Você pode criar um através da Central de Administração ou da API:

1. Crie uma integração personalizada na Central de Administração em Apps e integrações.
2. Registre o URL de destino do seu webhook.
3. Configure quais eventos receber (como conversation:message).
4. Defina opções adicionais como includeFullUser e includeFullSource para payloads mais detalhados.

Principais eventos de webhook para mensagens

A plataforma de mensagens suporta vários tipos de eventos:

Evento	Descrição
conversation:message	Qualquer mensagem enviada pelo usuário ou pela empresa
conversation:read	Mensagens lidas pelo usuário
conversation:postback	Usuário clicou em um botão de postback
passthrough:messaging	Dados de passagem específicos do canal

Entendendo o payload do webhook

Quando uma mensagem chega, o payload do webhook inclui tudo o que você precisa para responder adequadamente:

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "actor": {
      "id": "zd:answerBot",
      "name": "Support Bot",
      "type": "system"
    },
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "message": {
      "body": "Olá. Como posso ajudar você hoje?",
      "id": "67ab5f55155becd183e284cb"
    }
  },
  "type": "zen:event-type:messaging_ticket.message_added"
}

Os campos principais incluem o ID da conversa (para rastrear a thread), o conteúdo da mensagem e as informações do ator (se a mensagem veio de um usuário, agente ou sistema). Esses dados permitem que ferramentas de IA analisem as mensagens recebidas e gerem respostas contextuais automaticamente.

Métodos de autenticação e melhores práticas de segurança para configuração de webhooks de mensagens do Zendesk

Segurança é fundamental. Um endpoint de webhook não seguro pode vazar dados de clientes ou permitir que atores mal-intencionados injetem solicitações falsas.

Escolhendo o método de autenticação correto

Método	Melhor Para	Notas
Chave de API	Serviços de terceiros	Autenticação simples baseada em cabeçalho
Autenticação Básica	Serviços internos, chamadas de API do Zendesk	Use o formato {email}/token:{token}
Token de Portador	Serviços habilitados para OAuth	Padrão para APIs modernas
Nenhum	Apenas testes	Nunca use em produção

Verificando assinaturas de webhook

Para integrações críticas de segurança, o Zendesk fornece verificação de assinatura. Cada solicitação inclui dois cabeçalhos:

• X-Zendesk-Webhook-Signature: A assinatura principal
• X-Zendesk-Webhook-Signature-Timestamp: Carimbo de data/hora para verificação

Para verificar:

1. Extraia ambos os cabeçalhos da solicitação recebida.
2. Concatene o carimbo de data/hora e o corpo da solicitação.
3. Crie um hash HMAC SHA256 usando o segredo de assinatura do seu webhook.
4. Codifique o resultado em Base64.
5. Compare com o cabeçalho da assinatura.

O algoritmo se parece com isto: base64(HMACSHA256(TIMESTAMP + CORPO))

Se as assinaturas coincidirem, a solicitação é genuína. Caso contrário, rejeite-a.

Você pode encontrar seu segredo de assinatura na Central de Administração nas configurações do seu webhook (clique em "Revelar segredo"). Para testes antes da criação do webhook, use o segredo de teste estático: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

Recomendações de segurança

• Sempre use endpoints HTTPS
• Implemente a verificação de assinatura para webhooks de produção
• Torne os manipuladores de webhook idempotentes (o Zendesk pode tentar novamente ou enviar duplicatas)
• Monitore os logs de atividade do webhook para entregas com falha
• Use gerenciamento de segredos, não credenciais codificadas no código

Solução de problemas comuns na configuração de webhooks de mensagens do Zendesk

Mesmo webhooks bem configurados podem falhar. Veja como diagnosticar e corrigir os problemas mais comuns.

Erros de conexão

Erro	Causa	Solução
401/403	Credenciais inválidas	Verifique a chave de API ou token, confirme se o método de autenticação corresponde às expectativas do endpoint
404	URL do endpoint incorreto	Confirme se o caminho do URL e o domínio estão corretos
Tempo limite (Timeout)	Endpoint muito lento	Responda em até 12 segundos, processe os dados de forma assíncrona
Erro de SSL	Problema de certificado	Use um certificado válido assinado por uma CA (Let's Encrypt funciona bem)

Ativação do disjuntor (Circuit Breaker)

O Zendesk protege os endpoints de serem sobrecarregados. O disjuntor é acionado quando:

• 70% das solicitações falham em 5 minutos, OU
• Mais de 1.000 erros ocorrem em 5 minutos

Quando acionado, os webhooks pausam por 5 segundos. Após a pausa, o Zendesk tenta novamente. Uma solicitação bem-sucedida redefine o circuito — uma falha aciona outra pausa de 5 segundos. Esse ciclo continua até que seu endpoint se recupere.

O disjuntor não será acionado se ocorrerem menos de 100 solicitações em 5 minutos, portanto, webhooks de baixo volume geralmente estão a salvo de bloqueios acidentais.

Dicas de depuração

• Verifique a Central de Administração em Webhooks para logs de atividade (mantidos por 7 dias)
• Filtre os logs por status: filter[status]=failed
• Use ferramentas de monitoramento de solicitações para inspecionar os payloads reais
• Verifique se o formato do payload corresponde ao que seu endpoint espera
• Teste com ferramentas como Postman ou curl para isolar problemas

Comportamento de repetição (Retry)

Resposta	Comportamento
HTTP 409	Tenta novamente até 3 vezes
HTTP 429/503 com retry-after < 60s	Tenta novamente conforme o cabeçalho
Tempo limite (>12 segundos)	Tenta novamente até 5 vezes
Outros erros	Sem repetição automática

O Zendesk faz o melhor esforço para entregar webhooks uma vez, mas duplicatas ou eventos perdidos são possíveis. Projete seus manipuladores para serem idempotentes.

Simplifique as integrações de webhook com o eesel AI

Configurar webhooks é apenas o primeiro passo. Construir respostas inteligentes requer desenvolvimento adicional: analisar payloads, integrar com sua base de conhecimento, criar respostas contextuais e lidar com casos extremos. É aí que nós entramos.

O eesel AI conecta-se ao seu Zendesk e lida com a complexidade para você:

• Processamento em tempo real: Ingerimos eventos de tickets e mensagens conforme eles acontecem — nenhum desenvolvimento de webhook é necessário da sua parte.
• Respostas contextuais: Nossa IA usa sua base de conhecimento, tickets anteriores e central de ajuda para gerar respostas que combinam com a voz da sua marca.
• Ações além das respostas: Consulte pedidos no Shopify, processe reembolsos, atualize campos de tickets e muito mais — tudo configurado sem código.
• Implantação gradual: Comece com o modo copiloto (rascunho para revisão) antes de passar para respostas autônomas.

Começando com o eesel AI para Zendesk

A configuração leva minutos:

1. Conecte sua conta do Zendesk através do nosso painel.
2. Treine com seus dados existentes (tickets anteriores, artigos da central de ajuda, macros, documentos conectados).
3. Escolha seu modo: copiloto (agentes revisam rascunhos da IA) ou autônomo (a IA responde diretamente).
4. Execute simulações em tickets anteriores para verificar a qualidade antes de entrar no ar.

Isso elimina a necessidade de construir manipuladores de webhook personalizados, ao mesmo tempo que oferece automação de suporte baseada em IA. Implantações maduras alcançam até 81% de resolução autônoma com períodos de retorno do investimento inferiores a 2 meses.

Plano	Mensal	Anual	Interações/mês
Team	$299	$239/mês	1.000
Business	$799	$639/mês	3.000
Custom	Entre em contato	Personalizado	Ilimitado

O plano Business inclui Agente de IA para respostas autônomas, treinamento com tickets anteriores e recursos de simulação em massa. Experimente o eesel AI gratuitamente por 7 dias.