{
"title": "Como configurar um webhook do Zendesk para eventos de ticket criado",
"slug": "zendesk-webhook-ticket-created",
"locale": "pt",
"date": "2026-03-02",
"updated": "2026-03-02",
"template": "default",
"excerpt": "Um guia completo para configurar webhooks do Zendesk para notificações de novos tickets, incluindo etapas de configuração, exemplos de payload e cenários comuns de solução de problemas.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"Webhooks",
"Automation",
"Customer Support",
"API"
],
"readTime": 10,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como configurar um webhook do Zendesk para eventos de ticket criado",
"description": "Um guia completo para configurar webhooks do Zendesk para notificações de novos tickets, incluindo etapas de configuração, exemplos de payload e cenários comuns de solução de problemas.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-60c5f122-d5be-430f-ba9b-eb77123be95f"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-60c5f122-d5be-430f-ba9b-eb77123be95f",
"coverImageAlt": "Imagem do banner para Como configurar um webhook do Zendesk para eventos de ticket criado",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Posso configurar um webhook do Zendesk para eventos de ticket criado sem codificação?",
"answer": "Parcialmente. A criação do próprio webhook é feita por meio de apontar e clicar no Centro de Administração do Zendesk. No entanto, você ainda precisa de um URL de endpoint para receber os dados. Serviços como Zapier ou Make podem lidar com o lado do recebimento sem código personalizado, atuando como uma ponte entre o Zendesk e suas outras ferramentas."
},
{
"question": "Qual é a diferença entre assinaturas de eventos e webhooks conectados a gatilhos?",
"answer": "As assinaturas de eventos são acionadas para cada ocorrência de um tipo de evento com um payload fixo. Os webhooks conectados a gatilhos são acionados apenas quando condições específicas são atendidas, e você pode personalizar o payload. As assinaturas de eventos são mais simples, mas menos flexíveis. Você não pode alterar o método de conexão de um webhook após a criação."
},
{
"question": "Com que rapidez os webhooks do Zendesk são acionados após a criação de um ticket?",
"answer": "O Zendesk faz o 'melhor possível' para entregar webhooks quase em tempo real. A maioria é acionada em segundos após a ocorrência do evento. No entanto, durante períodos de alto volume ou incidentes, pode haver atrasos. Não crie sistemas que dependam da entrega de webhooks em menos de um segundo."
},
{
"question": "Posso filtrar quais tickets acionam meu webhook?",
"answer": "Apenas com webhooks conectados a gatilhos. Você pode adicionar condições como 'Prioridade é Alta' ou 'Grupo é Suporte' para limitar quando o webhook é acionado. As assinaturas de eventos são acionadas para cada ticket sem filtragem."
},
{
"question": "O que acontece se meu endpoint de webhook estiver inativo?",
"answer": "O Zendesk tenta novamente as entregas com falha com backoff exponencial. Para a maioria dos códigos de erro, ele tenta novamente até 3 vezes. Para timeouts, ele tenta novamente até 5 vezes. Se seu endpoint falhar consistentemente, o disjuntor do Zendesk desativará o webhook após atingir os limites de erro."
},
{
"question": "Existe uma alternativa mais simples aos webhooks do Zendesk para automação?",
"answer": "Sim. Ferramentas de suporte baseadas em IA, como o eesel AI, podem automatizar o tratamento de tickets sem nenhuma configuração de webhook. Você conecta sua conta do Zendesk e a IA aprende a marcar, rotear e responder aos tickets com base em seus dados históricos. Sem endpoints para manter, sem análise de payload, sem lógica de repetição para gerenciar."
}
],
"supportLink": null
}
}
---
Webhooks são uma das ferramentas mais poderosas no arsenal de automação do [Zendesk](https://www.zendesk.com). Eles permitem que você envie notificações em tempo real para sistemas externos sempre que algo acontece em seu help desk. Quando um cliente envia um novo ticket, um webhook pode alertar instantaneamente sua equipe no Slack, atualizar seu CRM ou acionar fluxos de trabalho personalizados em seus próprios aplicativos.
Configurar um webhook do Zendesk para eventos de ticket criado não é complicado, mas há algumas decisões importantes a serem tomadas ao longo do caminho. Este guia orienta você por todo o processo, desde a configuração inicial até os testes e a solução de problemas.
## O que você vai precisar
Antes de começar, certifique-se de que você tem:
- Uma conta do [Zendesk Support](https://www.zendesk.com) no plano Team ou superior (webhooks não estão disponíveis no plano Essential)
- Acesso de administrador ou uma função personalizada com permissões de criação de webhook
- Um URL de endpoint que pode receber solicitações HTTP POST (isso pode ser um serviço como Zapier, uma API personalizada ou um site de teste de webhook)
- Um token de API se você planeja usar autenticação (recomendado para produção)
Contas de avaliação têm algumas limitações: máximo de 10 webhooks e 60 invocações por minuto. Isso é suficiente para testes, mas você vai querer atualizar antes de entrar em operação com automação pesada.
## Passo 1: Criar o webhook no Zendesk
Primeiro, você precisa criar o próprio webhook. Isso define onde o Zendesk enviará os dados e como ele será autenticado.
Navegue até **Admin Center** → **Apps and integrations** → **Webhooks**. Clique em **Actions** no canto superior direito e, em seguida, selecione **Create webhook**.
Você verá um formulário com vários campos para configurar:
**Name and description:** Dê ao seu webhook um nome claro como "New Ticket Notification" para que você possa identificá-lo mais tarde. A descrição é opcional, mas útil se você tiver vários webhooks.
**Endpoint URL:** É aqui que o Zendesk enviará os dados do webhook. Deve ser um URL HTTPS válido que possa aceitar solicitações POST. Para testes, você pode usar um serviço como webhook.site para ver os payloads sem construir seu próprio endpoint.
**HTTP method:** Para assinaturas de eventos, isso deve ser POST. Se você estiver se conectando a gatilhos, em vez disso, você pode escolher GET, POST, PUT, PATCH ou DELETE, dependendo do que seu endpoint espera.
**Request format:** Para assinaturas de eventos, isso deve ser JSON. Webhooks conectados a gatilhos também suportam formatos XML e form-encoded.
**Authentication:** Isso é fortemente recomendado para produção. O Zendesk suporta três métodos:
- **API key:** Adiciona um cabeçalho personalizado com sua chave
- **Basic auth:** Nome de usuário e senha, codificados em base64
- **Bearer token:** Token estilo OAuth 2.0 no cabeçalho Authorization
Depois de preencher tudo, clique em **Create** na parte inferior. Seu webhook agora está criado, mas ainda não está conectado a nenhum evento. Esse é o próximo passo.
## Passo 2: Escolha seu método de conexão
Aqui é onde você precisa tomar uma decisão importante. O Zendesk oferece duas maneiras de conectar webhooks à atividade do ticket, e você não pode alterar isso mais tarde sem excluir e recriar o webhook.
### Opção A: Assinatura de evento (zen:event-type:ticket.created)
Esta abordagem inscreve seu webhook diretamente no fluxo de eventos do Zendesk. Quando qualquer ticket é criado, seu webhook é acionado.
**Prós:**
- É acionado para cada ticket criado, garantido
- Configuração simples: não são necessários gatilhos
- Entrega quase em tempo real
**Contras:**
- Estrutura de payload fixa (você não pode personalizar quais dados são enviados)
- Sem filtragem: você recebe todos os tickets, mesmo spam
- Deve usar POST e JSON
### Opção B: Webhook conectado a gatilho
Esta abordagem conecta seu webhook a um gatilho do Zendesk. O gatilho decide quando disparar com base nas condições que você define.
**Prós:**
- Controle total sobre quando o webhook é acionado (grupos específicos, prioridades, tags)
- Payload personalizável usando placeholders do Zendesk
- Pode filtrar ruído (spam, tickets de teste, etc.)
**Contras:**
- Requer a criação e manutenção de um gatilho
- Configuração um pouco mais complexa
**Qual você deve escolher?** Se você precisa de todos os tickets e não se importa em filtrar no seu lado, use assinaturas de eventos. Se você só quer tickets específicos (como problemas de alta prioridade ou tickets de certas organizações), use webhooks conectados a gatilhos.
## Passo 3: Configurar o gatilho (para webhooks conectados a gatilhos)
Se você escolheu a Opção B, agora você precisa criar um gatilho que invoque seu webhook.
Navegue até **Admin Center** → **Objects and rules** → **Triggers**. Clique em **Add trigger**.
**Defina suas condições:**
No mínimo, adicione: **Ticket** | **Is** | **Created**
Você pode adicionar mais condições para filtrar quais tickets acionam o webhook:
- Priority is High or Urgent
- Group is "Technical Support"
- Tags contain "escalated"
- Organization is a specific VIP customer
**Adicione a ação do webhook:**
Em **Actions**, selecione **Notify active webhook** no menu suspenso. Escolha o webhook que você criou no Passo 1.
**Configure o payload JSON:**
É aqui que você define quais dados são enviados para seu endpoint. Use placeholders do Zendesk para inserir dados do ticket:
```json
{
"ticket_id": "{{ticket.id}}",
"subject": "{{ticket.title}}",
"description": "{{ticket.description}}",
"requester_email": "{{ticket.requester.email}}",
"requester_name": "{{ticket.requester.name}}",
"priority": "{{ticket.priority}}",
"status": "{{ticket.status}}",
"group": "{{ticket.group.name}}",
"assignee": "{{ticket.assignee.name}}",
"created_at": "{{ticket.created_at}}",
"tags": "{{ticket.tags}}",
"url": "{{ticket.link}}"
}
O Zendesk substituirá cada placeholder pelos dados reais do ticket quando o webhook for acionado. Você também pode usar a marcação Liquid para lógica condicional.
Importante: Adicione uma condição de anulação para evitar loops infinitos. Como o gatilho é acionado quando um ticket é criado, e o webhook pode atualizar o ticket, você precisa de uma condição que impeça o gatilho de ser acionado novamente. Um padrão comum é adicionar uma tag em sua resposta de webhook e excluir tickets com essa tag.
Passo 4: Teste seu webhook
Antes de confiar em seu webhook em produção, você precisa verificar se ele funciona.
Teste através das configurações do webhook:
Volte para Admin Center → Apps and integrations → Webhooks. Encontre seu webhook e clique no menu de três pontos, depois em Test webhook.
O Zendesk enviará um payload de teste para seu endpoint. O teste usa um segredo de assinatura estático (dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==) para que você possa verificar a validação da assinatura.
Teste com um ticket real:
Crie um ticket de teste no Zendesk. Verifique seu endpoint para verificar:
- A solicitação chegou
- O payload contém os dados esperados
- Os cabeçalhos de autenticação estão presentes (se configurados)
- A assinatura é validada (se estiver usando HMAC)
Verifique os logs de atividade do webhook:
O Zendesk mantém logs de invocações de webhook por 7 dias. Você pode acessar estes através da API de Webhooks para ver o status de entrega, códigos de resposta e quaisquer erros.
Entendendo o payload do webhook
Quando o Zendesk envia um webhook para um evento de ticket criado, a estrutura do payload difere com base no seu método de conexão.
Payload inscrito no evento
Para assinaturas de eventos diretos, o payload segue um esquema fixo:
{
"type": "zen:event-type:ticket.created",
"account_id": 22129848,
"id": "cbe4028c-7239-495d-b020-f22348516046",
"time": "2025-01-08T10:12:07.672Z",
"zendesk_event_version": "2022-11-06",
"subject": "zen:ticket:5158",
"detail": {
"actor_id": "8447388090494",
"assignee_id": "8447388090494",
"brand_id": "8447346621310",
"created_at": "2025-01-08T10:12:07Z",
"description": "I need help with my order",
"id": "5158",
"is_public": true,
"organization_id": "8447346622462",
"priority": "LOW",
"requester_id": "8447388090494",
"status": "OPEN",
"subject": "Order help needed",
"tags": ["order", "help"],
"via": { "channel": "web_service" }
},
"event": { "meta": { "sequence": { "id": 12345, "position": 1 } } }
}
Os campos-chave incluem o ID do ticket, assunto, descrição, ID do solicitante, prioridade, status e timestamp de criação.
Payload conectado a gatilho
Para webhooks conectados a gatilhos, o payload é o que você definiu na ação do gatilho. Você tem controle total sobre a estrutura e o conteúdo.
Autenticação e segurança
Webhooks podem transportar dados confidenciais do ticket, por isso é importante protegê-los.
Métodos de autenticação:
- API key: Adicione um cabeçalho como
X-API-Key: your-secret-key - Basic auth: Nome de usuário:senha codificados em Base64 no cabeçalho Authorization
- Bearer token: Estilo OAuth 2.0
Authorization: Bearer your-token
Verificação de assinatura HMAC:
O Zendesk suporta assinaturas HMAC-SHA256 para verificar a autenticidade do webhook. Cada webhook recebe um segredo de assinatura exclusivo. O Zendesk assina cada solicitação computando um HMAC sobre o timestamp e o corpo da solicitação.
Seu endpoint deve:
- Extrair a assinatura do cabeçalho
x-zendesk-webhook-signature - Extrair o timestamp do cabeçalho
x-zendesk-webhook-signature-timestamp - Calcular a assinatura esperada usando seu segredo de assinatura
- Comparar usando comparação de tempo constante para evitar ataques de tempo
Melhores práticas:
- Sempre use endpoints HTTPS
- Verifique as assinaturas em produção
- Armazene segredos de assinatura com segurança (não em repositórios de código)
- Implemente idempotência para lidar com entregas duplicadas
- Retorne o status 200 rapidamente; processe assincronamente se necessário
Solução de problemas comuns
Mesmo com uma configuração cuidadosa, os webhooks às vezes não funcionam como esperado. Aqui estão os problemas mais comuns e como corrigi-los.
Webhook não está sendo acionado:
- Verifique as condições do gatilho: elas estão realmente sendo atendidas?
- Verifique se o gatilho está ativo (não desativado)
- Procure condições de anulação que possam impedir a execução
- Confirme se o status do webhook é "ativo"
Erros de endpoint (respostas 4xx, 5xx):
- 410 Gone: Seu endpoint retornou um erro; verifique os logs do seu servidor
- 429 Too Many Requests: Você está sendo limitado por taxa; implemente backoff
- Erros 5xx: Problemas do lado do servidor no seu lado
Problemas de timeout:
O Zendesk tem um timeout estrito de 10 segundos. Se seu endpoint não responder em 10 segundos, o Zendesk o marcará como falha e tentará novamente. Certifique-se de que seu endpoint responda rapidamente, processando o trabalho pesado de forma assíncrona, se necessário.
Disjuntor acionado:
Se seu webhook falhar a uma taxa de erro de 70% ou acumular mais de 1.000 erros em 5 minutos, o Zendesk o desativará automaticamente. Você precisará corrigir o problema subjacente e reativar o webhook manualmente.
Logs de atividade ausentes:
O Zendesk mantém logs de atividade de webhook apenas por 7 dias. Se você precisar de uma retenção mais longa, precisará registrar os eventos de webhook em sua própria infraestrutura.
Alternativa: Automatizar sem webhooks
Webhooks são poderosos, mas nem sempre são a ferramenta certa. Eles exigem configuração técnica, manutenção contínua e tratamento de erros. Se você quer automação sem a complexidade, existem alternativas.
Nós construímos o eesel AI para lidar com a automação de suporte sem exigir webhooks ou desenvolvimento personalizado. Em vez de configurar endpoints e analisar payloads JSON, você simplesmente conecta o eesel AI à sua conta do Zendesk. Ele aprende com seus tickets passados e artigos da central de ajuda, então lida com tarefas de rotina automaticamente.
Aqui está a diferença:
| Abordagem | Tempo de configuração | Habilidade técnica necessária | Manutenção |
|---|---|---|---|
| Webhooks | 2-4 horas | Desenvolvedor necessário | Monitoramento contínuo |
| eesel AI | 10 minutos | Nenhuma | Automática |
Com o eesel AI, você pode:
- Auto-tag e rotear tickets com base no conteúdo
- Rascunhar respostas para seus agentes
- Lidar com perguntas comuns de ponta a ponta
- Escalar problemas complexos para humanos
A melhor parte? Você pode testá-lo em tickets passados antes de entrar em operação. Sem risco de quebrar fluxos de trabalho de produção enquanto você ajusta a configuração.
Comece a automatizar seus fluxos de trabalho do Zendesk hoje
Configurar um webhook do Zendesk para eventos de ticket criado lhe dá visibilidade em tempo real de novas solicitações de suporte. Se você está notificando canais do Slack, sincronizando com um CRM ou acionando fluxos de trabalho personalizados, os webhooks fornecem a cola entre o Zendesk e o resto da sua stack.
O processo é simples: crie o webhook, escolha seu método de conexão, configure um gatilho (se necessário) e teste completamente. Preste atenção à autenticação e ao tratamento de erros para garantir uma operação confiável.
Se os webhooks parecem exagerados para suas necessidades, considere se uma abordagem baseada em IA pode funcionar melhor. Ferramentas como o eesel AI podem automatizar o tratamento de tickets sem qualquer configuração de webhook ou gerenciamento de endpoint. Você pode experimentar o eesel AI gratuitamente e ver como ele lida com seus tipos de ticket específicos antes de se comprometer com uma solução baseada em webhook.
De qualquer forma, o objetivo é o mesmo: gaste menos tempo no gerenciamento manual de tickets e mais tempo realmente ajudando os clientes.
Compartilhe esta postagem
Article by
