Webhook de conversa criada no Zendesk Messaging: Um guia de implementação completo

Notificações em tempo real são a espinha dorsal dos fluxos de trabalho de suporte modernos. Quando um cliente inicia uma conversa, seus sistemas precisam saber imediatamente, não quando alguém verifica manualmente se há atualizações. Os webhooks preenchem essa lacuna.

Mas aqui está a questão sobre o Zendesk: eles têm dois sistemas de webhook completamente diferentes, e o webhook "conversa criada" funciona de forma diferente do que a maioria das pessoas espera. Este guia elimina a confusão e mostra exatamente como configurar e usar webhooks de conversa no Zendesk, seja você criando integrações de IA, sincronizando dados com seu CRM ou roteando notificações para o Slack.

O que é o webhook de conversa criada no Zendesk Messaging?

Vamos esclarecer um equívoco comum primeiro. Quando as pessoas pesquisam por "webhook de conversa criada no Zendesk Messaging", geralmente estão pensando na plataforma de mensagens Sunshine Conversations (a infraestrutura que alimenta o Zendesk Messaging). Mas o evento real de "conversa criada" reside em um sistema diferente.

O Zendesk tem duas arquiteturas de webhook:

Webhooks padrão do Zendesk lidam com tickets, usuários, organizações e, sim, eventos de conversa. Estes vivem no Admin Center em Apps e integrações.

Webhooks de Messaging (Sunshine Conversations) lidam com mensagens de chat em tempo real através da plataforma de mensagens. Estes são configurados separadamente e usam diferentes tipos de eventos.

O evento conversation.created que você está procurando? Faz parte do sistema de webhook padrão, não da plataforma de mensagens. Isso confunde muitos desenvolvedores que esperam encontrá-lo na documentação de mensagens.

Então, o que esse webhook realmente faz? Quando uma nova conversa é iniciada em sua conta do Zendesk, seja do Web Widget, SDK móvel, WhatsApp ou qualquer outro canal, este webhook é acionado e envia um payload para seu endpoint com todos os detalhes da conversa. Seu aplicativo pode então reagir em tempo real: acionar um agente de IA, registrar em seu data warehouse, enviar uma notificação ou rotear a conversa com base no canal de origem.

Pré-requisitos para configurar webhooks de messaging

Antes de começar a configurar webhooks, certifique-se de que você tem:

• Acesso de administrador ao Zendesk Admin Center - Você precisará de permissões para criar webhooks e gerenciar integrações
• Uma URL de endpoint pronta para receber payloads - Esta deve ser uma URL HTTPS acessível publicamente que possa aceitar solicitações POST
• Compreensão básica da segurança de webhook - Você vai querer verificar as assinaturas para garantir que as solicitações são realmente do Zendesk
• Um plano para lidar com novas tentativas e falhas - Seu endpoint precisa responder em até 12 segundos ou o Zendesk tentará novamente

Uma limitação importante a saber: as contas de teste são limitadas a 10 webhooks e 60 invocações por minuto. Se você estiver testando em uma avaliação, planeje de acordo.

Como criar um webhook de conversa no Zendesk

Existem duas maneiras de configurar seu webhook: através da interface do usuário do Admin Center ou via API. A interface do usuário é mais rápida para configurações únicas, enquanto a API funciona melhor se você estiver automatizando implantações ou gerenciando vários ambientes.

Usando o Admin Center

Passo 1: Acesse a seção de webhooks

Navegue até o Admin Center, então clique em Apps e integrações na barra lateral. Selecione Webhooks > Webhooks no submenu.

Passo 2: Crie o webhook

Clique em Criar webhook e escolha seu método de conexão. Para eventos de conversa, selecione Eventos do Zendesk (não Acionador ou Automação).

A escolha do método de conexão é permanente. Depois de criar um webhook como "Eventos do Zendesk", você não pode convertê-lo em um webhook baseado em acionador posteriormente. Se você precisar de ambos os tipos de eventos, crie webhooks separados.

Passo 3: Configure as configurações do webhook

Preencha a configuração básica:

• Nome e Descrição - Use algo descritivo como "Notificações de Nova Conversa" para que sua equipe saiba o que ele faz
• URL do Endpoint - Seu endpoint HTTPS que receberá os payloads
• Método de solicitação - POST (isso é fixo para webhooks inscritos em eventos)
• Formato de solicitação - JSON (também fixo para assinaturas de eventos)

Passo 4: Selecione o evento de conversa criada

Na seção de assinaturas de eventos, selecione zen:event-type:conversation.created no menu suspenso. Você pode se inscrever em vários eventos, se necessário (como conversation.updated ou conversation.closed).

Passo 5: Configure a autenticação

Escolha seu método de autenticação:

Para produção, você também deve habilitar a verificação de assinatura. O Zendesk assina cada solicitação com HMAC SHA256, e você pode verificar a assinatura em relação ao segredo de assinatura do seu webhook para garantir que as solicitações sejam legítimas.

Usando a API

Para configuração programática, use a API de Webhooks:

curl -X POST https://{subdomain}.zendesk.com/api/v2/webhooks \
  -u {email_address}/token:{api_token} \
  -H "Content-Type:application/json" \
  -d '{
    "webhook": {
      "name": "Webhook de Conversa Criada",
      "status": "active",
      "endpoint": "https://your-endpoint.com/webhook",
      "http_method": "POST",
      "request_format": "json",
      "subscriptions": [
        "zen:event-type:conversation.created"
      ],
      "authentication": {
        "type": "bearer_token",
        "data": {
          "token": "YOUR_TOKEN"
        },
        "add_position": "header"
      }
    }
  }'

A API retorna um ID de webhook exclusivo que você usará para monitoramento e atualizações.

Entendendo o payload do webhook de conversa criada

Quando uma conversa é criada, o Zendesk envia um payload JSON para seu endpoint. Aqui está o que você pode esperar:

{
  "account_id": 21825834,
  "detail": {
    "id": "141"
  },
  "event": {
    "conversation_id": "67ab5f53a96f98663935c3f2",
    "created_at": "2025-02-11T14:32:05Z",
    "source_channel": "web",
    "participant_count": 1
  },
  "id": "01JQMQH83YNAKWSWJ8B1QH2NSC",
  "subject": "zen:ticket:141",
  "time": "2025-02-11T14:32:05.254571515Z",
  "type": "zen:event-type:conversation.created",
  "zendesk_event_version": "2022-11-06"
}

Campos-chave para prestar atenção:

• detail.id - O ID do ticket associado a esta conversa
• event.conversation_id - O identificador exclusivo da conversa
• event.source_channel - De onde a conversa se originou (web, whatsapp, facebook, etc.)
• type - O tipo de evento que acionou este webhook

A estrutura do payload difere dos webhooks de messaging (que usam um array events aninhado com tipos conversation:message). Os webhooks de conversa padrão têm uma estrutura mais plana focada no ciclo de vida da conversa, em vez de mensagens individuais.

Autenticação e melhores práticas de segurança

Os webhooks são tão seguros quanto seu processo de verificação. Como seu endpoint é acessível publicamente, você precisa verificar se as solicitações realmente vêm do Zendesk.

Verificação de assinatura

Cada solicitação de webhook inclui dois cabeçalhos:

• X-Zendesk-Webhook-Signature - A assinatura HMAC SHA256
• X-Zendesk-Webhook-Signature-Timestamp - Timestamp Unix de quando a solicitação foi enviada

Para verificar uma solicitação:

1. Extraia ambos os cabeçalhos da solicitação de entrada
2. Concatene o timestamp e o corpo da solicitação (timestamp + "." + body)
3. Gere um hash HMAC SHA256 usando o segredo de assinatura do seu webhook
4. Codifique o resultado em Base64
5. Compare com o cabeçalho de assinatura

O algoritmo é: base64(HMACSHA256(TIMESTAMP + "." + BODY))

Você pode encontrar seu segredo de assinatura no Admin Center clicando em "Revelar segredo" na página de configurações do seu webhook. Para testar antes de criar o webhook, use este segredo de teste estático: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==

Requisito HTTPS

Sempre use endpoints HTTPS para webhooks de produção. Além dos benefícios de segurança, alguns recursos como cabeçalhos personalizados e certos métodos de autenticação só funcionam com HTTPS.

Idempotência

O Zendesk faz o possível para entregar webhooks exatamente uma vez, mas não pode garantir isso. Seu endpoint pode receber o mesmo evento de conversa criada várias vezes, especialmente durante novas tentativas ou se o disjuntor for ativado.

Projete seu manipulador para ser idempotente: verifique se você já processou um ID de conversa antes de tomar uma atitude. Isso evita notificações duplicadas, entradas de CRM duplicadas ou o acionamento da mesma automação duas vezes.

Lidando com eventos de webhook em seu aplicativo

Aqui está um padrão básico para lidar com webhooks de conversa em Node.js:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  // Verify signature
  const signature = req.headers['x-zendesk-webhook-signature'];
  const timestamp = req.headers['x-zendesk-webhook-signature-timestamp'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('base64');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event asynchronously
  const event = req.body;

  if (event.type === 'zen:event-type:conversation.created') {
    // Queue for processing - don't block the response
    processConversationCreated(event);
  }

  // Respond quickly to prevent retries
  res.status(200).send('OK');
});

Os princípios-chave:

• Verifique a assinatura antes de processar
• Responda com 200 OK rapidamente (em até 12 segundos)
• Processe o evento de forma assíncrona - não deixe sua lógica de negócios bloquear a resposta HTTP
• Lide com eventos duplicados normalmente

Padrões de integração comuns

Acionamento de Agente de IA - Quando uma conversa é criada, verifique se um agente de IA deve lidar com ela primeiro antes de rotear para agentes humanos. Verifique o canal de origem, a hora do dia ou o segmento de cliente para tomar a decisão de roteamento.

Registro em CRM - Registre o início da conversa em seu CRM para relatórios e análises. Inclua a fonte do canal para entender de onde os clientes estão entrando em contato.

Notificações do Slack - Envie uma notificação para um canal do Slack quando conversas de alta prioridade começarem, ou roteie diferentes canais para diferentes canais do Slack com base na fonte.

Se você estiver criando integrações de IA e quiser pular o desenvolvimento do webhook completamente, o eesel AI se conecta diretamente ao Zendesk e lida com o processamento de conversas sem exigir manipuladores de webhook personalizados. Nós ouvimos os eventos de conversa e geramos automaticamente respostas contextuais com base em sua base de conhecimento.

Solução de problemas comuns de webhook

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

Erros de conexão

Ativação do disjuntor

Se seu endpoint começar a retornar erros, o disjuntor do Zendesk entrará em ação para proteger seu servidor de ser sobrecarregado. Ele é acionado quando uma porcentagem significativa de solicitações falha dentro de um curto período de tempo.

Quando ativado, os webhooks pausam brevemente. Após a pausa, o Zendesk tenta novamente. Se essa solicitação falhar, o disjuntor aciona outra pausa. Este ciclo continua até que uma solicitação seja bem-sucedida.

Nota: O disjuntor normalmente não será ativado em webhooks de baixo volume, então pequenos ambientes de teste geralmente estão seguros contra bloqueios acidentais.

Dicas de depuração

• Verifique os logs de atividade do webhook no Admin Center (retidos por 7 dias)
• Filtre por status para ver invocações com falha: adicione ?filter[status]=failed à solicitação da API
• Use ferramentas como ngrok ou Hookdeck para inspecionar os payloads reais durante o desenvolvimento
• Verifique se o formato do seu payload corresponde ao que seu endpoint espera - a estrutura difere entre webhooks padrão e webhooks de messaging

Referência de comportamento de nova tentativa

Simplifique as integrações de webhook com eesel AI

Construir manipuladores de webhook personalizados leva um tempo de desenvolvimento significativo. Você precisa lidar com a verificação de assinatura, lógica de nova tentativa, idempotência e tratamento de erros antes mesmo de chegar à sua lógica de negócios real. Então, há a manutenção contínua: monitoramento, registro e atualização à medida que as APIs do Zendesk evoluem.

Se seu objetivo é automação de suporte alimentada por IA em vez de infraestrutura de webhook, há um caminho mais simples.

eesel AI se conecta diretamente à sua conta do Zendesk e lida com toda a complexidade do webhook para você:

• Processamento de conversa em tempo real - Nós ingerimos eventos de ticket e messaging à medida que acontecem, sem necessidade de desenvolvimento de webhook do seu lado
• Respostas contextuais de IA - Nosso sistema usa sua base de conhecimento, tickets anteriores e artigos da central de ajuda para gerar respostas que correspondam à voz da sua marca
• Ações além do texto - Consulte pedidos no Shopify, processe reembolsos, atualize campos de ticket e muito mais, tudo configurado por meio de instruções em linguagem natural, em vez de código
• Implantação gradual - Comece com o modo copiloto, onde os agentes revisam os rascunhos da IA, então passe para respostas autônomas à medida que você ganha confiança

A configuração leva minutos, não dias. Conecte sua conta do Zendesk, treine em seus dados existentes e escolha seu modo. Você pode executar simulações em tickets anteriores para verificar a qualidade antes de entrar em operação.

Implantações maduras usando eesel AI alcançam até 81% de resolução autônoma com períodos de retorno típicos abaixo de 2 meses. Se você está considerando construir manipuladores de webhook personalizados para integração de IA, experimente o eesel AI gratuitamente por 7 dias primeiro e veja se ele cobre seu caso de uso.

Comece a construir com webhooks de conversa do Zendesk hoje

O webhook de conversa criada é uma ferramenta poderosa para automação de suporte em tempo real. Se você está acionando agentes de IA, sincronizando dados com sistemas externos ou roteando notificações, entender como configurar e lidar adequadamente com esses webhooks é essencial.

Lembre-se da distinção fundamental: os webhooks padrão lidam com eventos do ciclo de vida da conversa (criada, atualizada, fechada), enquanto os webhooks de messaging lidam com o fluxo de mensagens em tempo real. O evento conversation.created reside no sistema de webhook padrão, e é seu ponto de entrada para reagir a novas conversas de clientes em todos os canais.

Comece com a interface do usuário do Admin Center para se familiarizar com a estrutura do payload, então passe para a API quando estiver pronto para automatizar. Habilite a verificação de assinatura desde o primeiro dia, projete para idempotência e responda rapidamente para evitar tempestades de novas tentativas.

Para equipes que estão construindo suporte alimentado por IA sem a sobrecarga de infraestrutura, eesel AI elimina a necessidade de manipuladores de webhook personalizados, ao mesmo tempo em que fornece respostas contextuais baseadas em conhecimento. De qualquer forma, a conscientização da conversa em tempo real está agora ao seu alcance.