Como configurar webhooks de mensagem entregue do Zendesk Messaging

Webhooks transformam seu Zendesk em um mecanismo de notificação em tempo real. Em vez de pesquisar atualizações, os webhooks enviam dados para seus sistemas no momento em que algo acontece. Para mensagens especificamente, os webhooks de entrega permitem que você rastreie se as mensagens realmente chegam aos seus clientes. Não apenas entregues ao WhatsApp ou Twilio. Realmente entregues.

Isso é importante porque "enviado" e "entregue" são duas coisas diferentes. Uma mensagem pode sair do Zendesk, falhar no nível da operadora e você nunca saberia sem o rastreamento de entrega. Ou pode ficar não entregue porque o telefone de um cliente está offline. Os webhooks de entrega oferecem visibilidade de todo o ciclo de vida da mensagem.

Neste guia, você aprenderá como configurar webhooks de entrega de mensagens do Zendesk do zero. Abordaremos os três tipos de eventos de entrega, percorreremos a configuração passo a passo e forneceremos código funcional que você pode adaptar para sua própria implementação.

O que você vai precisar

Antes de mergulhar, certifique-se de que você tem:

• Uma conta Zendesk com acesso de administrador (a configuração do webhook requer permissões de administrador)
• Um endpoint HTTPS para receber payloads de webhook (um servidor de desenvolvimento funciona bem para testes)
• Familiaridade básica com conceitos de JSON e HTTP
• Opcionalmente: uma ferramenta como Postman ou curl para teste

Se você estiver construindo isso para produção, também vai querer pensar em autenticação, tratamento de erros e idempotência. Abordaremos todos esses pontos.

Entendendo os eventos de entrega de mensagens do Zendesk

A plataforma de mensagens do Zendesk envia três tipos de eventos de entrega. Cada um informa algo diferente sobre onde sua mensagem está.

Os três tipos de eventos de entrega

Veja como o fluxo funciona. Quando você envia uma mensagem, ela primeiro atinge a API do canal. Se essa API aceitar a mensagem, você receberá um evento delivery:channel. Para alguns canais (como WhatsApp ou SMS via Twilio), você pode receber posteriormente um evento delivery:user confirmando que a mensagem chegou ao dispositivo. Se algo falhar ao longo do caminho, você receberá delivery:failure com informações de erro específicas.

O sinalizador isFinalEvent informa se mais eventos estão chegando. Quando isFinalEvent: true, este é o último webhook que você receberá para essa mensagem. Quando false, o canal oferece suporte à confirmação de entrega no nível do usuário, então espere um acompanhamento.

Suporte de canal varia

Nem todos os canais podem confirmar a entrega ao usuário. Alguns apenas confirmam que receberam a mensagem do Zendesk. Aqui está a discriminação:

Canais com confirmação de entrega completa (canal + usuário):

• WhatsApp
• Twilio SMS
• MessageBird
• iOS SDK, Android SDK, Unity SDK, Web Widget

Canais com entrega apenas no canal:

• Facebook Messenger
• Instagram
• LINE
• Telegram
• Viber
• WeChat
• X (Twitter)
• Apple Messages for Business

Para canais sem confirmação do usuário, o evento delivery:channel terá isFinalEvent: true. Esse é o seu sinal de que não haverá mais atualizações.

Por que isso é importante para sua implementação

Se você estiver construindo análises em cima desses webhooks, vai querer levar em conta essa variação. Uma métrica "entregue" significa coisas diferentes dependendo do canal. Para o WhatsApp, é a confirmação no nível do dispositivo. Para o Facebook Messenger, significa apenas que a API do Facebook aceitou a mensagem.

Passo 1: Criar um webhook no Centro de Administração do Zendesk

Vamos percorrer a criação do seu primeiro webhook de entrega.

Primeiro, navegue até Centro de Administração > Aplicativos e integrações > Webhooks. Se você não vir a opção Webhooks, verifique se sua função tem as permissões adequadas. Saiba mais na documentação de webhooks do Zendesk.

Clique em Criar webhook. Você verá um formulário com vários campos:

Nome: Dê a ele algo descritivo como "Rastreador de Entrega de Mensagens" ou "Eventos de Entrega de Produção".

URL do Endpoint: É aqui que o Zendesk POSTará os payloads do webhook. Para desenvolvimento, você pode usar uma ferramenta como ngrok para expor um servidor local. Para produção, este deve ser um URL HTTPS em sua infraestrutura.

Método HTTP: Selecione POST. Os eventos de entrega sempre usam POST.

Formato da solicitação: Selecione JSON.

Não salve ainda. Configuraremos as assinaturas de eventos e a autenticação nas próximas etapas.

Passo 2: Inscrever-se em eventos de entrega

No formulário de criação do webhook, encontre a seção Assinaturas de eventos. É aqui que você especifica quais eventos devem acionar seu webhook.

Para rastreamento de entrega de mensagens, inscreva-se nestes três eventos:

1. conversation:message:delivery:channel
2. conversation:message:delivery:user
3. conversation:message:delivery:failure

Você pode se inscrever em eventos adicionais, se necessário (como conversation:message para todas as mensagens), mas para rastreamento de entrega especificamente, esses três são o que você deseja.

Opções de filtragem de eventos:

Se sua integração faz parte do switchboard, você pode controlar se recebe eventos para conversas que não está gerenciando ativamente. A configuração deliverStandbyEvents filtra isso. A maioria das integrações define isso como false para receber apenas eventos para conversas ativas.

Salve o webhook. O Zendesk atribuirá a ele um ID exclusivo (começando com 01). Copie este ID. Você precisará dele para testes e para conectar a gatilhos, se seguir esse caminho.

Passo 3: Configurar a autenticação do webhook

Webhooks sem autenticação são um risco de segurança. Qualquer pessoa que descobrir o URL do seu endpoint pode enviar eventos falsos. O Zendesk oferece suporte a vários métodos de autenticação.

Opções de autenticação disponíveis

Para a maioria das implementações, a autenticação de chave de API atinge o equilíbrio certo entre segurança e simplicidade.

Configurando no Zendesk

No formulário do webhook, expanda a seção Autenticação. Selecione seu método preferido e insira as credenciais:

• Para chave de API: especifique o nome do cabeçalho (por exemplo, X-API-Key) e o valor da chave
• Para token de portador: insira o token que o Zendesk deve incluir
• Para autenticação básica: forneça nome de usuário e senha

Verificando assinaturas de webhook

O Zendesk pode assinar webhooks usando HMAC-SHA256. Isso permite que você verifique se os payloads realmente vieram do Zendesk, não de um invasor. Consulte a documentação de assinatura de webhook do Zendesk para obter orientação detalhada sobre a implementação.

Para habilitar isso, você precisará:

1. Gerar um segredo de assinatura (o Zendesk fornece isso quando você habilita a assinatura)
2. Verificar o cabeçalho X-Zendesk-Webhook-Signature em seu endpoint
3. Calcular o HMAC-SHA256 do payload usando seu segredo
4. Compará-lo com o cabeçalho de assinatura

Aqui está um exemplo simples de Node.js:

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('base64');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Passo 4: Construir seu endpoint de webhook

Agora para a parte divertida: construir o endpoint que recebe esses webhooks.

Requisitos básicos

Seu endpoint deve:

• Usar HTTPS (o Zendesk rejeita URLs HTTP)
• Responder em 10 segundos
• Retornar um código de status 2xx para processamento bem-sucedido
• Lidar com eventos duplicados normalmente (idempotência)

Receptor de webhook de amostra (Node.js/Express)

Aqui está um endpoint mínimo, mas pronto para produção:

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/zendesk-delivery', (req, res) => {
  // Acknowledge receipt immediately
  res.status(200).send('OK');

  // Process events asynchronously
  const events = req.body.events || [];

  for (const event of events) {
    handleDeliveryEvent(event);
  }
});

function handleDeliveryEvent(event) {
  const { type, payload } = event;

  switch (type) {
    case 'conversation:message:delivery:channel':
      console.log(`Message ${payload.message.id} delivered to ${payload.destination.type}`);
      break;

    case 'conversation:message:delivery:user':
      console.log(`Message ${payload.message.id} reached user`);
      break;

    case 'conversation:message:delivery:failure':
      console.error(`Message ${payload.message.id} failed:`, payload.error);
      break;
  }
}

app.listen(3000, () => {
  console.log('Webhook endpoint listening on port 3000');
});

Coisas importantes que este exemplo faz:

1. Responde imediatamente (200 OK) antes do processamento
2. Processa eventos de forma assíncrona
3. Lida com cada tipo de evento separadamente
4. Extrai IDs relevantes para registro/depuração

Lidando com repetições e idempotência

O Zendesk repete webhooks com falha (respostas 4xx/5xx, timeouts) até 3-5 vezes, dependendo do erro. Isso significa que seu endpoint pode receber o mesmo evento várias vezes.

Para lidar com isso, implemente a idempotência:

const processedEvents = new Set(); // Use Redis in production

function handleDeliveryEvent(event) {
  if (processedEvents.has(event.id)) {
    console.log(`Skipping duplicate event: ${event.id}`);
    return;
  }

  // Process the event...

  processedEvents.add(event.id);
}

Em produção, use Redis ou um banco de dados para rastrear IDs de eventos processados com TTL (tempo de vida) para que a janela de desduplicação corresponda ao comportamento de repetição do Zendesk.

Passo 5: Entendendo o payload do webhook de entrega

Vamos detalhar o que realmente chega nesses webhooks.

Estrutura de payload comum

Todos os eventos de entrega compartilham esta estrutura de wrapper:

{
  "app": {
    "id": "5fb29b20fee5422428712475"
  },
  "webhook": {
    "id": "5ff5e98b0d0c6d8925594923",
    "version": "v2"
  },
  "events": [
    {
      "id": "5ff7595eafcaab0a685ff889",
      "createdAt": "2021-01-07T18:56:30.666Z",
      "type": "conversation:message:delivery:channel",
      "payload": {
        "conversation": { "id": "2d4fd3d00715d1e64611e248" },
        "user": { "id": "71268330a47f5c4b541fce46" },
        "destination": {
          "type": "whatsapp",
          "integrationId": "5ff75853b1c3000a6ad4f7f5"
        },
        "message": { "id": "5ff7595eb1c3000a6ad4f7fb" },
        "isFinalEvent": false,
        "externalMessages": [
          { "id": "wamid.HBgNNTUxQTk4MDUz5Tg4MRU..." }
        ]
      }
    }
  ]
}

Campos-chave explicados

Especificidades do evento de falha

Quando a entrega falha, o payload inclui um objeto de erro:

{
  "error": {
    "code": "bad_request",
    "message": "Message failed to send because more than 24 hours have passed since the customer last replied.",
    "underlyingError": {
      "errors": [{
        "code": 131047,
        "title": "Re-engagement message",
        "message": "Re-engagement message"
      }]
    }
  }
}

O campo underlyingError contém o erro bruto da API do canal. Isso é inestimável para depuração. Os códigos de erro do WhatsApp, por exemplo, informam exatamente por que uma mensagem foi rejeitada.

Passo 6: Testar sua implementação de webhook

Antes de entrar em produção, você precisa verificar se tudo funciona.

Usando o testador de webhook do Zendesk

Na página de configuração do webhook, clique em Testar webhook. O Zendesk enviará um payload de teste para seu endpoint e mostrará a resposta. Isso é útil para verificar a conectividade e a autenticação.

No entanto, o payload de teste é genérico. Não será um evento de entrega real. Para testes realistas, você precisa acionar fluxos de mensagens reais.

Testando com mensagens reais

1. Envie uma mensagem de teste através do Zendesk Messaging
2. Verifique os logs do seu endpoint para webhooks de entrada
3. Verifique se a estrutura do payload corresponde às expectativas
4. Confirme se sua lógica de tratamento de eventos processa cada tipo corretamente

Para canais que oferecem suporte à entrega do usuário (como o WhatsApp), você pode verificar o fluxo de dois eventos. O primeiro webhook deve ter isFinalEvent: false. O segundo (entrega do usuário) deve ter isFinalEvent: true.

Verificando os logs de atividade do webhook

O Zendesk mantém logs de webhook por 7 dias. Navegue até Centro de Administração > Aplicativos e integrações > Webhooks, selecione seu webhook e visualize a guia Atividade. Isso mostra entregas recentes, códigos de resposta e quaisquer erros.

Se você não estiver vendo os webhooks esperados, verifique:

• O webhook está ativo (não pausado)?
• As assinaturas de eventos estão corretas?
• Seu endpoint está respondendo com códigos de status 2xx?

Solução de problemas comuns

Mesmo com uma configuração cuidadosa, as coisas dão errado. Aqui estão os problemas mais comuns e como corrigi-los.

Webhook não está sendo acionado

Se você não estiver recebendo webhooks quando as mensagens são enviadas:

• Verifique se o webhook está ativo (não pausado ou em estado de rascunho)
• Verifique se os tipos de evento corretos estão inscritos
• Para webhooks conectados por gatilho, verifique se as condições do gatilho estão sendo atendidas
• Verifique os logs de atividade do webhook para padrões de falha

Erros de autenticação (401/403)

Se o Zendesk relatar falhas de autenticação:

• Verifique se seu endpoint está verificando o cabeçalho correto
• Confirme se a chave/token da API não expirou
• Verifique a sensibilidade a maiúsculas e minúsculas nos nomes dos cabeçalhos
• Se estiver usando a verificação de assinatura, certifique-se de que está calculando o HMAC corretamente

Timeouts e disjuntor

O Zendesk tem um timeout de 10 segundos. Se seu endpoint demorar mais:

• Responda imediatamente (200 OK) e processe de forma assíncrona
• Use uma fila de mensagens (SQS, RabbitMQ, etc.) para processamento pesado
• Monitore os tempos de processamento e otimize operações lentas

O disjuntor é acionado com uma taxa de erro de 70% ou mais de 1.000 erros em 5 minutos. Se isso acontecer, o Zendesk pausa seu webhook. Você precisará corrigir o problema subjacente e reativar o webhook manualmente.

Eventos de entrega ausentes

Se você estiver vendo alguns eventos, mas não outros:

• Verifique a matriz de suporte do canal. Nem todos os canais enviam confirmações de entrega do usuário.
• Para o WhatsApp especificamente, os eventos de entrega do usuário podem ser atrasados ou suprimidos se a mensagem for recebida fora de um determinado período.
• Verifique o comportamento de isFinalEvent. Se for true no nível do canal, nenhum evento de entrega do usuário seguirá.

Melhores práticas para produção

Depois que seu webhook estiver funcionando, considere estas recomendações de produção.

Tratamento de erros e monitoramento

• Registre todos os recebimentos de webhook com IDs de evento para depuração
• Configure alertas para taxas de erro elevadas
• Monitore os tempos de resposta do endpoint
• Rastreie as taxas de entrega por canal para identificar problemas precocemente

Segurança

• Sempre use HTTPS em produção
• Implemente a verificação de assinatura do webhook
• Gire as chaves de API periodicamente
• Não registre dados confidenciais do payload

Retenção de dados

Os eventos de entrega contêm metadados de mensagem. Considere:

• Por quanto tempo reter os logs de eventos
• Se deve armazenar payloads completos ou apenas campos-chave
• Requisitos de conformidade (GDPR, etc.) para dados de mensagem

Quando pesquisar vs. usar webhooks

Webhooks são ideais para atualizações em tempo real. Mas se você precisar de dados históricos ou eventos perdidos, pode precisar complementar com a pesquisa. A API List Messages pode preencher lacunas.

Simplifique os fluxos de trabalho de mensagens com eesel AI

Construir endpoints de webhook personalizados leva tempo de engenharia. Você precisa lidar com autenticação, repetições, idempotência e casos de erro. Então você precisa construir a lógica de negócios real em cima desses eventos.

Nós construímos eesel AI para lidar com essa complexidade para você. Em vez de gerenciar webhooks você mesmo, você obtém automação de mensagens turnkey com rastreamento de entrega integrado. Nosso colega de equipe de IA se integra ao Zendesk (e Freshdesk, Gorgias e outros) para lidar com conversas de ponta a ponta.

Se você está procurando um caminho mais rápido para mensagens com tecnologia de IA, confira nosso guia completo para webhooks de mensagens do Zendesk. E se você quiser comparar opções, veja nossa análise dos melhores chatbots de IA para Zendesk.