{
"title": "Formato de payload do webhook do Zendesk: Um guia completo para desenvolvedores",
"slug": "zendesk-webhook-payload-format",
"locale": "pt",
"date": "2026-03-02",
"updated": "2026-03-02",
"template": "default",
"excerpt": "Um guia abrangente para entender os formatos de payload do webhook do Zendesk, desde a anatomia da solicitação até esquemas específicos de eventos e verificação de segurança.",
"categories": [
"Zendesk",
"Guides"
],
"tags": [
"Zendesk",
"Webhooks",
"API",
"Integration",
"Customer Support"
],
"readTime": 11,
"author": 16,
"reviewer": 14,
"seo": {
"title": "Formato de payload do webhook do Zendesk: Um guia completo para desenvolvedores",
"description": "Um guia abrangente para entender os formatos de payload do webhook do Zendesk, desde a anatomia da solicitação até esquemas específicos de eventos e verificação de segurança.",
"image": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-34a7235d-94f7-4258-8c7a-bb8cb1fe95af"
},
"coverImage": "https://wmeojibgfvjvinftolho.supabase.co/storage/v1/object/public/public_assets/blog-gen/banner-34a7235d-94f7-4258-8c7a-bb8cb1fe95af",
"coverImageAlt": "Imagem do banner para o formato de payload do webhook do Zendesk: Um guia completo para desenvolvedores",
"coverImageWidth": 1920,
"coverImageHeight": 1080,
"faqs": {
"heading": "Perguntas frequentes",
"type": "blog",
"answerType": "html",
"faqs": [
{
"question": "Qual é o formato exato do payload do webhook do Zendesk para eventos de criação de tickets?",
"answer": "Os eventos de criação de tickets usam um esquema JSON padrão com propriedades de nível superior, incluindo type, account_id, id, time, subject, detail e event. O objeto detail contém o registro completo do ticket com campos como id, subject, description, status, priority, requester_id e assignee_id."
},
{
"question": "Como verifico a autenticidade de um formato de payload do webhook do Zendesk?",
"answer": "Use a verificação de assinatura HMAC-SHA256. Extraia os cabeçalhos x-zendesk-webhook-signature e x-zendesk-webhook-signature-timestamp e, em seguida, calcule base64(HMACSHA256(TIMESTAMP + BODY)) usando o segredo de assinatura do seu webhook. Compare isso com o cabeçalho de assinatura usando comparação de tempo constante."
},
{
"question": "Posso personalizar o formato de payload do webhook do Zendesk para webhooks baseados em gatilhos?",
"answer": "Sim. Os webhooks de gatilho e automação permitem personalização total usando espaços reservados de marcação Liquid como {{ticket.id}}, {{ticket.title}} e {{ticket.requester.email}}. Você pode estruturar o payload como JSON, XML ou dados codificados em formulário."
},
{
"question": "Qual é o tamanho máximo para um formato de payload de webhook do Zendesk personalizado?",
"answer": "Os payloads personalizados para webhooks de gatilho têm um limite de tamanho máximo de 256 KB. Se o seu payload exceder isso, o Zendesk o truncará. Monitore payloads que incluem campos de descrição grandes ou dados de campo personalizados extensos."
},
{
"question": "O formato de payload do webhook do Zendesk inclui cabeçalhos de autenticação?",
"answer": "Cada solicitação de webhook inclui cabeçalhos padrão: x-zendesk-account-id, x-zendesk-webhook-id, x-zendesk-webhook-invocation-id, x-zendesk-webhook-signature e x-zendesk-webhook-signature-timestamp. Você também pode configurar chave de API, autenticação básica ou token de portador."
},
{
"question": "Como testo o formato de payload do webhook do Zendesk durante o desenvolvimento?",
"answer": "Use webhook.site para capturar e inspecionar payloads brutos ou use o recurso de teste de webhook integrado do Zendesk no Admin Center. Para testes de pré-criação, use o segredo de assinatura estático: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ=="
}
],
"supportLink": null
}
}
---
Webhooks transformam sua conta do Zendesk em um mecanismo de notificação em tempo real. Em vez de sondar APIs em busca de atualizações, os webhooks enviam dados para seus sistemas no momento em que algo acontece: um ticket é criado, um agente atualiza uma prioridade ou um cliente envia feedback. Mas para construir integrações confiáveis, você precisará entender exatamente quais dados o Zendesk envia e como eles são estruturados.
Este guia detalha o formato de payload do webhook do Zendesk desde o início. Você aprenderá sobre os dois tipos de webhooks que o Zendesk oferece, a estrutura exata dos payloads de eventos, como verificar a autenticidade do webhook e dicas práticas de implementação. Quer você esteja construindo uma integração personalizada ou conectando o Zendesk a ferramentas de terceiros, entender esses formatos de payload é essencial.
Na eesel AI, processamos dados de webhook do Zendesk e de outras plataformas para impulsionar a automação inteligente. Obter o formato de payload correto é o primeiro passo para construir integrações robustas e seguras.
## Os dois tipos de webhooks do Zendesk
O Zendesk oferece dois métodos de conexão de webhook fundamentalmente diferentes, e a escolha que você faz determina suas opções de formato de payload. Você não pode alterar essa decisão posteriormente, por isso vale a pena entender ambas as abordagens antecipadamente.
### Webhooks inscritos em eventos
Esses webhooks se inscrevem diretamente em [eventos do sistema Zendesk](https://developer.zendesk.com/api-reference/webhooks/event-types/webhook-event-types/). Quando um usuário é criado, um [status do ticket](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#status) é alterado ou uma organização é atualizada, o Zendesk envia automaticamente um webhook para seu endpoint.
Aqui está o que você precisa saber:
- **Método HTTP:** POST apenas
- **Formato da solicitação:** JSON apenas
- **Estrutura do payload:** Esquema fixo definido pelo Zendesk
- **Melhor para:** Notificações em tempo real sobre atividades de usuário, organização, central de ajuda ou mensagens
O payload é previsível. O Zendesk controla quais dados são enviados, o que significa menos flexibilidade, mas também menos espaço para erros de configuração.
### Webhooks de gatilho e automação
Estes se conectam às regras de negócios do Zendesk: [gatilhos](https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/) e [automações](https://developer.zendesk.com/api-reference/ticketing/business-rules/automations/). Você define exatamente quando o webhook é acionado com base nas condições do ticket.
Características principais:
- **Métodos HTTP:** GET, POST, PUT, PATCH, DELETE
- **Formato da solicitação:** JSON, XML ou codificado em formulário
- **Estrutura do payload:** Totalmente personalizável usando espaços reservados de marcação Liquid
- **Melhor para:** Fluxos de trabalho baseados em tickets com lógica condicional
Essa abordagem oferece controle completo sobre o payload. Você decide quais dados incluir e como formatá-los.
### Escolhendo a abordagem certa
| Fator | Inscrito em eventos | Gatilho/automação |
|--------|------------------|-------------------|
| Flexibilidade | Baixa (esquema fixo) | Alta (payloads personalizados) |
| Complexidade da configuração | Simples | Mais complexo |
| Caso de uso | Eventos em todo o sistema | Fluxos de trabalho específicos do ticket |
| Tamanho do payload | Definido pelo sistema | Máximo de 256 KB |
Se você precisar reagir às alterações do ticket com lógica personalizada, use webhooks de gatilho. Para eventos de sistema mais amplos, como criação de usuário ou atividade de mensagens, os webhooks inscritos em eventos são a melhor opção.
## Anatomia de uma solicitação de webhook
Cada solicitação de webhook do Zendesk inclui cabeçalhos HTTP padrão que fornecem metadados sobre a solicitação. Entender esses cabeçalhos é crucial para roteamento, registro e verificação de segurança.
### Cabeçalhos padrão
| Cabeçalho | Descrição | Exemplo |
|--------|-------------|---------|
| `x-zendesk-account-id` | Seu identificador de conta do Zendesk | `123456` |
| `x-zendesk-webhook-id` | Identificador exclusivo para este webhook | `01F1KRFQ6BG29CNWFR60NK5FNY` |
| `x-zendesk-webhook-invocation-id` | ID de invocação específico | `8350205582` |
| `x-zendesk-webhook-signature` | Assinatura HMAC-SHA256 para verificação | `EiqWE3SXTPQpPulBV6OSuuGziIishZNc1VwNZYqZrHU=` |
| `x-zendesk-webhook-signature-timestamp` | Timestamp ISO 8601 | `2021-03-25T05:09:27Z` |
Os cabeçalhos de assinatura são opcionais, mas recomendados para integrações de produção. Eles permitem que você verifique se as solicitações realmente vieram do Zendesk e ajudam a evitar ataques de repetição.
### Diferenças na estrutura da solicitação
Os webhooks inscritos em eventos sempre usam POST com payloads JSON. O corpo contém os dados completos do evento em um esquema padronizado.
Os webhooks de gatilho variam com base na sua configuração. Uma solicitação GET pode incluir parâmetros na URL, enquanto as solicitações POST incluem um corpo formatado como JSON, XML ou dados codificados em formulário, dependendo das suas configurações.
## Estrutura e exemplos do payload do evento
Os webhooks inscritos em eventos usam um esquema JSON consistente em todos os tipos de eventos. Depois de entender a estrutura, analisar qualquer evento se torna simples.
### Esquema de evento padrão
Cada payload de evento inclui estas propriedades de nível superior:
```json
{
"type": "zen:event-type:ticket.created",
"account_id": 12514403,
"id": "2b24ef10-19d4-4740-93cf-8f98ec4776c0",
"time": "2099-07-04T05:33:18Z",
"zendesk_event_version": "2022-06-20",
"subject": "zen:ticket:12345",
"detail": { /* detalhes do recurso */ },
"event": { /* informações de alteração */ }
}
| Propriedade | Descrição |
|---|---|
type | O identificador do tipo de evento |
account_id | Seu ID de conta do Zendesk |
id | ID exclusivo do evento |
time | Quando o evento ocorreu |
zendesk_event_version | Versão do esquema (atualmente "2022-06-20") |
subject | Domínio e identificador de recurso |
detail | Objeto de recurso completo |
event | O que mudou (para eventos de atualização) |
Evento de ticket criado
Quando um novo ticket é criado, o Zendesk envia um payload como este:
{
"account_id": 22129848,
"detail": {
"actor_id": "8447388090494",
"assignee_id": "8447388090494",
"brand_id": "8447346621310",
"created_at": "2025-01-08T10:12:07Z",
"description": "I need help with my recent order",
"external_id": null,
"form_id": "8646151517822",
"group_id": "8447320466430",
"id": "5158",
"is_public": true,
"organization_id": "8447346622462",
"priority": "LOW",
"requester_id": "8447388090494",
"status": "OPEN",
"subject": "Order help request",
"submitter_id": "8447388090494",
"tags": ["order-help"],
"type": "TASK",
"updated_at": "2025-01-08T10:12:07Z",
"via": { "channel": "web_service" }
},
"event": {
"meta": {
"sequence": {
"id": 39313930383633353634323835,
"position": 1
}
}
},
"id": "cbe4028c-7239-495d-b020-f22348516046",
"subject": "zen:ticket:5158",
"time": "2025-01-08T10:12:07.672717030Z",
"type": "zen:event-type:ticket.created",
"zendesk_event_version": "2022-11-06"
}
O objeto detail contém o registro completo do ticket. O objeto event para eventos de criação inclui apenas metadados sobre a sequência de eventos.
Evento de status alterado
Os eventos de atualização incluem um objeto event mais detalhado mostrando o que mudou:
{
"event": {
"current": "OPEN",
"meta": {
"sequence": {
"id": 39313930383633353634323835,
"position": 1
}
},
"previous": "NEW"
}
}
As propriedades current e previous mostram os valores antes e depois. Para alterações de status, os valores possíveis incluem: NEW, OPEN, PENDING, HOLD, SOLVED, CLOSED, DELETED, ARCHIVED e SCRUBBED.
Evento de prioridade alterada
Os eventos de prioridade seguem o mesmo padrão:
{
"event": {
"current": "URGENT",
"meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
"previous": "NORMAL"
}
}
Os valores de prioridade são: LOW, NORMAL, HIGH e URGENT.
Evento de comentário adicionado
Quando alguém adiciona um comentário a um ticket:
{
"event": {
"comment": {
"author": {
"id": "8659716080510",
"is_staff": false,
"name": "John Smith"
},
"body": "Thanks for the quick response!",
"id": "8659716087550",
"is_public": true
},
"meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } }
}
}
O objeto de comentário inclui o texto completo, informações do autor e status de visibilidade.
Evento de tags alteradas
Para atualizações de tags, o Zendesk mostra o que foi adicionado e removido:
{
"event": {
"meta": { "sequence": { "id": 39313930383633353634323835, "position": 1 } },
"tags_added": ["urgent", "vip"],
"tags_removed": ["pending-review"]
}
}
Essa estrutura facilita o rastreamento de alterações de tags sem comparar arrays completos.
Payloads e espaços reservados de webhook de gatilho
Os webhooks de gatilho e automação oferecem controle completo sobre o formato do payload usando espaços reservados de marcação Liquid.
Espaços reservados comuns
| Espaço reservado | Descrição |
|---|---|
{{ticket.id}} | ID do ticket |
{{ticket.title}} | Assunto do ticket |
{{ticket.description}} | Descrição do ticket |
{{ticket.status}} | Status atual |
{{ticket.priority}} | Nível de prioridade |
{{ticket.requester.email}} | E-mail do solicitante |
{{ticket.requester.name}} | Nome do solicitante |
{{ticket.assignee.email}} | E-mail do responsável |
{{ticket.group.name}} | Nome do grupo |
{{ticket.organization.name}} | Nome da organização |
{{ticket.tags}} | Tags separadas por vírgula |
{{ticket.created_at}} | Timestamp de criação |
{{ticket.updated_at}} | Timestamp da última atualização |
{{current_user.name}} | Usuário que acionou a ação |
Exemplo de payload JSON personalizado
Você pode construir payloads personalizados como este:
{
"event": "ticket_updated",
"ticket_id": "{{ticket.id}}",
"ticket_url": "{{ticket.url}}",
"subject": "{{ticket.title}}",
"description": "{{ticket.description}}",
"status": "{{ticket.status}}",
"priority": "{{ticket.priority}}",
"requester": {
"name": "{{ticket.requester.name}}",
"email": "{{ticket.requester.email}}"
},
"assignee": {
"name": "{{ticket.assignee.name}}",
"email": "{{ticket.assignee.email}}"
},
"tags": "{{ticket.tags}}",
"updated_by": "{{current_user.name}}"
}
Limites de tamanho do payload
Os payloads personalizados têm um tamanho máximo de 256 KB. Se o seu payload exceder esse limite, o Zendesk o truncará. Você vai querer ficar de olho em payloads que incluem campos de descrição grandes ou muitos campos personalizados.
Autenticação e segurança
Proteger seus endpoints de webhook é fundamental. O Zendesk oferece várias opções de autenticação para verificar as solicitações recebidas.
Verificação de assinatura
O método mais seguro usa assinaturas HMAC-SHA256. O Zendesk gera uma assinatura a partir do timestamp e do corpo da solicitação, que você pode verificar em seu servidor.
Algoritmo: base64(HMACSHA256(TIMESTAMP + BODY))
Exemplo de verificação Node.js:
const crypto = require("crypto");
const SIGNING_SECRET = "your_webhook_signing_secret";
const SIGNING_SECRET_ALGORITHM = "sha256";
function isValidSignature(signature, body, timestamp) {
let hmac = crypto.createHmac(SIGNING_SECRET_ALGORITHM, SIGNING_SECRET);
let sig = hmac.update(timestamp + body).digest("base64");
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(sig)
);
}
Exemplo de verificação Python:
import hmac
import hashlib
import base64
def verify_signature(payload, signature, timestamp, secret):
message = timestamp + payload
computed = base64.b64encode(
hmac.new(
secret.encode('utf-8'),
message.encode('utf-8'),
hashlib.sha256
).digest()
).decode('utf-8')
return hmac.compare_digest(computed, signature)
Segredos de assinatura
Cada webhook tem um segredo de assinatura exclusivo. Você pode recuperá-lo no Admin Center do Zendesk clicando em "Reveal secret" na página de detalhes do webhook ou por meio da API em GET /api/v2/webhooks/{id}/signing_secret.
Para testar webhooks antes da criação, use este segredo estático: dGhpc19zZWNyZXRfaXNfZm9yX3Rlc3Rpbmdfb25seQ==
Métodos de autenticação adicionais
Além da verificação de assinatura, o Zendesk oferece suporte a:
- Autenticação de chave de API: Adicione um cabeçalho personalizado com sua chave de API
- Autenticação básica: Nome de usuário e senha ou token de API
- Token de portador: Autenticação de token no estilo OAuth
Melhores práticas de segurança
- Sempre use endpoints HTTPS
- Verifique as assinaturas em ambientes de produção
- Valide os timestamps para evitar ataques de repetição (rejeite solicitações com mais de 5 minutos)
- Armazene segredos em variáveis de ambiente, nunca no código
- Torne seus manipuladores de webhook idempotentes (o Zendesk pode tentar novamente ou enviar duplicatas)
Testes e solução de problemas
Antes de implantar webhooks em produção, você precisará de estratégias de teste confiáveis.
Usando webhook.site
Webhook.site fornece uma URL temporária e gratuita que captura as solicitações recebidas. É perfeito para inspecionar payloads de webhook brutos durante o desenvolvimento. Você obtém uma URL exclusiva que exibe cabeçalhos e conteúdo do corpo em tempo real.
Teste integrado do Zendesk
Ao criar ou editar um webhook no Admin Center, o Zendesk fornece um recurso de teste. Você pode enviar um payload de teste para seu endpoint e ver a resposta. Isso ajuda a verificar a conectividade e o formato do payload antes de entrar em operação.
Erros e soluções comuns
| Erro | Causa | Solução |
|---|---|---|
| 401 Não autorizado | Falha na autenticação | Verifique as chaves de API, tokens ou verificação de assinatura |
| 403 Proibido | Endpoint rejeitou a solicitação | Verifique se o endpoint aceita POST/GET conforme configurado |
| 404 Não encontrado | URL do endpoint errada | Verifique novamente a URL do webhook |
| Timeout | Endpoint muito lento | Otimize o tempo de resposta ou verifique a carga do servidor |
| Disjuntor acionado | Muitos erros | Corrija os problemas do endpoint e aguarde a reinicialização automática |
Comportamento de repetição
O Zendesk tenta novamente webhooks com falha automaticamente:
- Erros HTTP 409: até 3 tentativas
- HTTP 429/503 com cabeçalho retry-after abaixo de 60 segundos: repetido
- Timeouts (limite de 12 segundos): até 5 tentativas
O disjuntor é ativado quando 70% das solicitações falham em 5 minutos ou mais de 1.000 erros ocorrem. Ele pausa o webhook por 5 segundos e, em seguida, tenta uma solicitação. Se for bem-sucedido, a operação normal é retomada.
Integrando webhooks com eesel AI
Os webhooks se tornam mais poderosos quando combinados com processamento inteligente. Na eesel AI, ajudamos as equipes a automatizar fluxos de trabalho processando dados de webhook do Zendesk e de outras plataformas.
Veja como a integração de webhook aprimora as operações de suporte:
- Triagem inteligente: Processe webhooks de criação de tickets para categorizar e rotear automaticamente os tickets com base na análise de conteúdo
- Respostas automatizadas: Acione respostas contextuais usando dados de webhook sobre status do ticket e alterações de prioridade
- Enriquecimento de dados: Combine payloads de webhook com fontes de dados internas para fornecer aos agentes um contexto abrangente do cliente
- Sincronização entre plataformas: Use webhooks para manter o Zendesk sincronizado com CRM, inventário ou outros sistemas de negócios
Nossa integração com o Zendesk se conecta diretamente à sua conta, aprendendo com seus tickets anteriores e central de ajuda para fornecer automação inteligente. Os webhooks estendem essa capacidade, permitindo gatilhos e ações em tempo real.
Principais conclusões e melhores práticas
Construir integrações de webhook confiáveis requer atenção aos detalhes. Aqui está o que você vai querer lembrar:
Escolha o tipo de webhook certo: Os webhooks inscritos em eventos funcionam melhor para notificações em todo o sistema, enquanto os webhooks de gatilho oferecem flexibilidade para fluxos de trabalho específicos do ticket.
Verifique as assinaturas em produção: A verificação de assinatura HMAC-SHA256 garante que as solicitações venham do Zendesk e não tenham sido adulteradas.
Lide com as repetições normalmente: O Zendesk pode tentar novamente solicitações com falha ou enviar duplicatas. Projete seus manipuladores para serem idempotentes.
Monitore a saúde do webhook: Use o log de atividades e o status do disjuntor para detectar problemas precocemente.
Teste completamente: Use ferramentas como webhook.site para inspecionar payloads antes de implantar em produção.
Entender o formato de payload do webhook do Zendesk é a base para construir integrações robustas. Com a abordagem certa para segurança, testes e tratamento de erros, você pode criar conexões confiáveis que mantêm seus sistemas sincronizados e sua equipe informada.
Compartilhe esta postagem
Article by
