{
"title": "Como configurar webhooks do Zendesk para atualizações de tickets: Guia completo",
"slug": "zendesk-webhook-ticket-updated",
"locale": "pt",
"date": "2026-03-02",
"updated": "2026-03-02",
"template": "default",
"excerpt": "Um guia completo para configurar webhooks do Zendesk que são acionados quando os tickets são atualizados, incluindo instruções passo a passo e exemplos do mundo real.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"Webhooks",
"Ticket Management",
"API",
"Automation"
],
"readTime": 10,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Como configurar webhooks do Zendesk para atualizações de tickets: Guia completo",
"description": "Um guia completo para configurar webhooks do Zendesk que são acionados quando os tickets são atualizados, incluindo instruções passo a passo e exemplos do mundo real.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-fa02975f-be07-43c0-a6e9-3aa26261fd4f"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-fa02975f-be07-43c0-a6e9-3aa26261fd4f",
"coverImageAlt": "Imagem do banner para Como configurar webhooks do Zendesk para atualizações de tickets: Guia completo",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas Frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Como acionar um webhook do Zendesk quando o responsável por um ticket é atualizado?",
"answer": "Crie um gatilho com a condição 'Ticket > Responsável > Alterado' e adicione a ação 'Notificar webhook ativo'. Use o espaço reservado {{ticket.assignee.name}} em seu payload para capturar o novo responsável."
},
{
"question": "Posso configurar um webhook do Zendesk para atualizações de tickets sem codificação?",
"answer": "A configuração do webhook em si não requer codificação, mas você precisa de um endpoint para receber os dados do webhook. Serviços como Zapier ou Make podem fornecer endpoints sem código que recebem webhooks do Zendesk e se conectam a outros aplicativos."
},
{
"question": "Por que meu webhook do Zendesk não está sendo acionado quando os tickets são atualizados?",
"answer": "Verifique três coisas: (1) suas condições de gatilho realmente correspondem às atualizações do ticket, (2) o status do webhook está 'ativo' e não 'inativo' e (3) seu endpoint retornou respostas 200 anteriormente (o disjuntor pode estar ativo se houver falhas)."
},
{
"question": "Quais dados posso enviar em um payload de webhook do Zendesk atualizado?",
"answer": "Qualquer campo de ticket usando espaços reservados do Zendesk: {{ticket.id}}, {{ticket.title}}, {{ticket.status}}, {{ticket.priority}}, {{ticket.assignee.name}}, {{ticket.requester.email}}, {{ticket.latest_comment}}, campos personalizados via {{ticket.ticket_field_ID}} e muito mais."
},
{
"question": "Como evitar entregas de webhook duplicadas para a mesma atualização de ticket?",
"answer": "Use o cabeçalho x-zendesk-webhook-invocation-id para rastrear webhooks processados. Armazene IDs no Redis ou em seu banco de dados com um TTL de 24 horas e ignore o processamento se você já tiver visto o ID antes."
},
{
"question": "Existe um limite para quantos webhooks posso criar no Zendesk?",
"answer": "As contas de avaliação são limitadas a 10 webhooks. As contas pagas têm limites mais altos, embora o Zendesk possa limitar a criação excessiva de webhooks. Entre em contato com o suporte se precisar aumentar seu limite."
},
{
"question": "Posso atualizar um ticket por meio de um webhook quando ele é atualizado?",
"answer": "Sim, usando o que alguns chamam de 'webhooks internos'. Crie um webhook apontando para https://yoursubdomain.zendesk.com/api/v2/tickets/{{ticket.id}}.json com o método PUT e seu token de API. Use isso para modificar o mesmo ticket que acionou o webhook, mas sempre adicione uma condição de anulação para evitar loops infinitos."
}
],
"supportLink": null
}
}
---
Os webhooks do Zendesk permitem que você crie integrações em tempo real que respondem à atividade do ticket. Quando um ticket é atualizado, seja uma alteração de responsável, mudança de status ou novo comentário, você pode notificar automaticamente sistemas externos sem escrever scripts de polling complexos.
Este guia explica como configurar um webhook que é acionado quando os tickets são atualizados. Você aprenderá as etapas exatas para configurar webhooks no Admin Center do Zendesk, conectá-los a gatilhos e lidar com problemas comuns que atrapalham os implementadores iniciantes.
## O que são webhooks do Zendesk e por que usá-los?
Webhooks são callbacks HTTP que enviam solicitações para um URL especificado quando algo acontece no Zendesk. Pense neles como notificações automatizadas que enviam dados para seus sistemas em vez de você ter que buscá-los.
O Zendesk oferece duas maneiras de conectar webhooks:
- **Webhooks inscritos em eventos** são disparados para cada ocorrência de um evento do sistema. Inscreva-se em "ticket atualizado" e seu endpoint recebe um payload cada vez que qualquer ticket é alterado. Eles usam payloads JSON fixos e solicitações POST.
- **Webhooks conectados a gatilhos ou automação** são disparados com base nas condições que você define. Você escolhe exatamente quando eles são acionados (responsável alterado, prioridade definida como urgente, etc.) e personaliza o payload usando espaços reservados do Zendesk.
Casos de uso comuns para webhooks de atualização de tickets incluem sincronizar dados de tickets com um [CRM](https://www.salesforce.com/products/sales-cloud/overview/), alertar canais do [Slack](https://slack.com) sobre alterações de alta prioridade, acionar fluxos de trabalho personalizados em suas ferramentas internas e criar trilhas de auditoria para conformidade.
O principal benefício é a capacidade de resposta em tempo real. Em vez de pesquisar a API do Zendesk a cada poucos minutos para verificar se há alterações, você será notificado instantaneamente quando algo acontecer.
Para equipes que acham a configuração do webhook muito técnica ou demorada, o [eesel AI](https://www.eesel.ai) oferece uma abordagem alternativa. Em vez de construir e manter a infraestrutura de webhook, o eesel se conecta diretamente ao Zendesk e lida com a automação por meio de IA que aprenderá com seus tickets existentes.
## O que você precisará antes de começar
Antes de criar seu primeiro webhook, certifique-se de ter:
- **Acesso de administrador ao Zendesk** somente administradores podem criar e gerenciar webhooks por meio do Admin Center
- **Um token de API** gere isso no Admin Center em Aplicativos e integrações > Tokens de API
- **Um endpoint de recebimento** um URL que pode aceitar solicitações HTTP POST e processar payloads JSON
- **Conhecimento básico de JSON** você estará construindo payloads com dados de tickets
Opcional, mas recomendado: configure um inspetor de solicitação como [Hookdeck Console](https://console.hookdeck.com) ou [webhook.site](https://webhook.site) para teste. Essas ferramentas fornecem um URL temporário para capturar solicitações de webhook e inspecionar a estrutura do payload antes de conectar seu endpoint de produção.
## Passo a passo: Criando um webhook para atualizações de tickets
### Passo 1: Navegue até webhooks no Admin Center
Faça login no Zendesk e acesse o Admin Center. Vá para **Aplicativos e integrações > Webhooks**. Consulte a [documentação oficial de webhooks do Zendesk](https://developer.zendesk.com/documentation/webhooks/) para obter mais detalhes.
Se este for seu primeiro webhook, a lista estará vazia. Clique no menu suspenso **Ações** no canto superior direito e selecione **Criar webhook**.
### Passo 2: Crie um novo webhook
Você verá duas opções de conexão:
- **Gatilho ou automação** para fluxos de trabalho baseados em tickets com condições personalizadas
- **Eventos do Zendesk** para assinaturas de eventos em todo o sistema
Escolha **Gatilho ou automação**, pois você desejará disparar o webhook quando os tickets forem atualizados com condições específicas.
Dê ao seu webhook um nome descritivo como "Notificador de atualização de ticket" para que você possa identificá-lo mais tarde ao conectar-se a gatilhos.
### Passo 3: Configure as configurações do webhook
Preencha os detalhes do endpoint:
- **URL do endpoint**: O URL HTTPS onde o Zendesk enviará solicitações POST
- **Método de solicitação**: Escolha com base nos requisitos do seu endpoint (POST para a maioria dos casos de uso, PUT para atualizar recursos)
- **Formato da solicitação**: JSON é recomendado para dados de tickets
O URL do endpoint deve ser acessível publicamente. O Zendesk não pode enviar webhooks para localhost ou endereços somente internos. Se você estiver testando, use um serviço como [ngrok](https://ngrok.com) para tunelar seu servidor de desenvolvimento local.
### Passo 4: Configure a autenticação
Escolha como o Zendesk se autentica com seu endpoint:
- **Nenhum** sem autenticação (não recomendado para produção)
- **Autenticação básica** nome de usuário e senha no cabeçalho de autorização
- **Token de portador** autenticação de token no estilo OAuth 2.0
- **Chave de API** cabeçalho personalizado com um nome e valor de chave
Para a autenticação básica, use seu endereço de e-mail do Zendesk com `/token` anexado como o nome de usuário (por exemplo, `voce@empresa.com/token`) e seu token de API como a senha.
### Passo 5: Teste o webhook
Antes de salvar, clique no botão **Testar**. O Zendesk enviará um payload de amostra para seu endpoint.
Insira um ID de ticket existente para o teste. O payload de teste não atualizará nada, apenas verifica a conectividade.
Verifique os logs do seu endpoint ou o inspetor de solicitação para confirmar se o teste chegou. Se você vir uma resposta 200, a configuração do seu webhook está funcionando.
### Passo 6: Crie um gatilho para disparar o webhook
Agora você precisa de um gatilho que invoque seu webhook quando os tickets forem atualizados. Vá para **Objetos e regras > Gatilhos** e clique em **Adicionar gatilho**.
Defina as condições que determinam quando o webhook é disparado:
- **Ticket > O ticket é** Atualizado
- Adicione quaisquer condições adicionais (opcional): Ticket > Responsável > Alterado, Ticket > Status > Alterado para, etc.
Para a ação, selecione **Notificar webhook ativo** e escolha o webhook que você acabou de criar no menu suspenso.
### Passo 7: Configure as condições do gatilho e o payload
Na ação do gatilho, você definirá o payload JSON que é enviado para seu endpoint. Use espaços reservados do Zendesk para incluir dados do ticket:
```json
{
"ticket_id": "{{ticket.id}}",
"subject": "{{ticket.title}}",
"status": "{{ticket.status}}",
"assignee": "{{ticket.assignee.name}}",
"requester": "{{ticket.requester.email}}",
"updated_at": "{{ticket.updated_at_with_timestamp}}"
}
O espaço reservado ticket.updated_at_with_timestamp é particularmente útil para fluxos de trabalho de webhook, pois tem a hora exata da atualização, que você pode usar para evitar condições de corrida.
Salve o gatilho. O webhook agora está ativo e será disparado sempre que os tickets que corresponderem às suas condições forem atualizados.
Exemplos comuns de payload de webhook
Aqui estão configurações práticas de payload para cenários comuns:
Notificação básica de atualização de ticket:
{
"event": "ticket_updated",
"ticket_id": "{{ticket.id}}",
"subject": "{{ticket.title}}",
"status": "{{ticket.status}}",
"priority": "{{ticket.priority}}"
}
Alerta de alteração de responsável:
{
"event": "assignee_changed",
"ticket_id": "{{ticket.id}}",
"new_assignee": "{{ticket.assignee.name}}",
"new_assignee_email": "{{ticket.assignee.email}}",
"previous_assignee": "{{ticket.assignee.previous.name}}"
}
Alteração de status com comentário:
{
"event": "status_changed",
"ticket_id": "{{ticket.id}}",
"new_status": "{{ticket.status}}",
"latest_comment": "{{ticket.latest_comment}}",
"ticket_url": "{{ticket.link}}"
}
Atualização de campo personalizado:
{
"ticket_id": "{{ticket.id}}",
"custom_fields": [
{"id": 12345, "value": "{{ticket.ticket_field_12345}}"},
{"id": 67890, "value": "{{ticket.ticket_field_67890}}"}
]
}
Solução de problemas comuns
Webhook não sendo disparado
Verifique as condições do seu gatilho cuidadosamente. Um erro comum é usar "Ticket é criado" em vez de "Ticket é atualizado" ou definir condições que nunca correspondem (como exigir que um campo esteja em branco e preenchido).
Adicione uma ação "Adicionar tags" ao seu gatilho temporariamente. Se a tag for adicionada, mas o webhook não for disparado, o problema está na configuração do webhook. Se a tag não for adicionada, as condições do seu gatilho estão erradas.
Erros de autenticação
Para autenticação básica, verifique se você está usando email@dominio.com/token como o nome de usuário (com /token anexado) e a string de token de API real como a senha, não sua senha do Zendesk.
Timeout de 10 segundos
O Zendesk impõe um timeout estrito de 10 segundos. Seu endpoint deve responder com um código de status 2xx dentro dessa janela. Se você precisar realizar operações lentas, responda imediatamente com 200 e processe de forma assíncrona em um job em segundo plano.
Ativação do disjuntor
Se 70% das suas solicitações de webhook falharem em 5 minutos ou você atingir mais de 1.000 erros, o Zendesk ativará um disjuntor que pausa as entregas por 5 segundos. Os eventos durante essas pausas são registrados como "disjuntor quebrado", mas nunca entregues. Monitore a saúde do seu endpoint e corrija os problemas rapidamente para evitar isso.
Entregas duplicadas
O Zendesk pode enviar o mesmo webhook várias vezes. Use o cabeçalho x-zendesk-webhook-invocation-id para desduplicar. Armazene os IDs processados no Redis ou em seu banco de dados com um TTL de 24 horas.
Verificando logs de invocação
Vá para Aplicativos e integrações > Webhooks, clique no seu webhook e, em seguida, na guia Invocações. Você pode ver os últimos 7 dias de tentativas de entrega, incluindo detalhes de solicitação e resposta. Esta é sua principal ferramenta de depuração.
Melhores práticas para webhooks de produção
Sempre use endpoints HTTPS. Webhooks HTTP não criptografados são vulneráveis à interceptação e não devem ser usados em produção.
Verifique as assinaturas do webhook. O Zendesk assina cada solicitação com HMAC-SHA256. Verifique a assinatura usando o segredo de assinatura do seu webhook para garantir que as solicitações realmente vieram do Zendesk, não de um invasor.
Implemente a idempotência. Armazene os IDs de invocação processados e ignore os duplicados. Isso evitará o processamento duplo quando o Zendesk tentar novamente as entregas com falha.
Responda imediatamente. Retorne uma resposta 200 o mais rápido possível e, em seguida, processe os dados do webhook de forma assíncrona. Isso mantém você dentro do timeout de 10 segundos e evita tempestades de repetição.
Monitore a saúde do webhook. Consulte a API de invocações de webhook regularmente para detectar falhas antes que se tornem críticas. O Zendesk não envia notificações de falha, então você precisa verificar proativamente.
Lide com as repetições normalmente. O Zendesk tentará novamente as respostas 409 até 3 vezes e as respostas 429/503 com cabeçalhos retry-after. Projete seu endpoint para lidar com isso normalmente sem criar dados duplicados.
Uma alternativa mais simples: eesel AI para automação de tickets
Configurar webhooks requer conhecimento técnico, manutenção contínua e monitoramento cuidadoso. Se sua equipe está procurando automação de tickets sem a sobrecarga de engenharia, o eesel AI oferece uma abordagem diferente.
Em vez de construir a infraestrutura de webhook, você conecta o eesel AI à sua conta do Zendesk e ele aprende com seus tickets existentes, artigos da central de ajuda e macros. A IA então lida com a automação por meio de ações nativas do Zendesk, para que você não precise de webhooks.
Principais diferenças da automação baseada em webhook:
- Configuração sem código conecte o Zendesk em minutos sem escrever código ou configurar endpoints
- Roteamento com tecnologia de IA marca, prioriza e roteia automaticamente os tickets com base no conteúdo, não apenas nas alterações de campo
- Aprendizado contínuo melhora com o tempo à medida que vê mais de seus tickets e correções de agentes
- Confiabilidade integrada sem disjuntores, problemas de timeout ou lógica de repetição para gerenciar
O eesel AI pode rascunhar respostas, escalar problemas complexos, atualizar campos de ticket e até mesmo processar reembolsos por meio da integração do Shopify, tudo sem configuração de webhook.
Comece a automatizar seu fluxo de trabalho do Zendesk hoje mesmo
Os webhooks do Zendesk oferecem poderosos recursos de integração em tempo real. Ao seguir as etapas deste guia, você pode configurar notificações de atualização de tickets que enviam dados para seu CRM, acionam fluxos de trabalho internos ou alertam os canais da equipe instantaneamente.
Os webhooks fazem sentido quando você precisa de controle total sobre a integração, tem recursos de engenharia para construir e manter endpoints e exige formatos de payload personalizados. Eles são a escolha certa para fluxos de trabalho complexos e multi-sistema.
Para equipes que desejam benefícios de automação sem a complexidade técnica, o eesel AI lida com o roteamento, marcação e respostas de tickets por meio de IA que aprende seu negócio. É um caminho mais rápido para a automação se os webhooks parecerem exagerados para sua situação.
Qualquer que seja a abordagem que você escolher, o objetivo é o mesmo: reduzir o manuseio manual de tickets para que sua equipe possa se concentrar em resolver os problemas dos clientes. Comece com um webhook simples para um caso de uso ou explore a automação baseada em IA e expanda a partir daí à medida que vir os resultados.
Compartilhe esta postagem
Article by
