Criação de webhooks para a interação com sistemas de terceiros

Caminho rápido: Central de administração > Aplicativos e integrações > Webhooks > Webhooks

Um webhook envia uma solicitação HTTP para uma URL específica em resposta a uma atividade no Zendesk Support. Por exemplo, você pode configurar um webhook para enviar solicitações quando um usuário for apagado ou um novo ticket for criado.

Os desenvolvedores da web normalmente usam webhooks para invocar um comportamento em outro sistema. Por exemplo, você pode usar webhooks para:

Alertar sua equipe no Slack quando um ticket urgente for criado
Encaminhar detalhes do ticket para sua equipe de documentação no Asana depois que um ticket for resolvido
Notificar seu próprio serviço back-end sobre um evento de ticket importante.

Você precisa ser um administrador ou um agente em uma função personalizada com permissão para criar webhooks. As contas de avaliação têm um limite máximo de 10 webhooks e um limite de taxa de 60 invocações por minuto.

Este artigo abrange os seguintes tópicos:

Sobre webhooks
Criação de webhooks
Teste de um webhook

Sobre webhooks

Há duas maneiras de conectar um webhook à atividade no Zendesk Support:

Inscrever o webhook em um ou mais eventos do Zendesk. Use este método de conexão para enviar solicitações com base na organização, usuário, central de ajuda ou atividade da comunidade. Para obter a lista de tipos de eventos compatíveis, consulte Tipos de eventos de webhook na referência da API.
Conectar um webhook a um gatilho ou automação. Use este método de conexão para enviar solicitações com base na atividade do ticket.

Um webhook inscrito em um evento do Zendesk não pode se conectar a um gatilho ou uma automação. Da mesma forma, um webhook conectado a um gatilho ou uma automação não pode se inscrever em eventos do Zendesk. Você não pode alterar um método de conexão do webhook.

Importante: é feita uma melhor tentativa de entregar eventos de webhook para ações no Zendesk para usuários o mais próximo possível do tempo real; entretanto, às vezes, há um atraso.

Inscrição em eventos do Zendesk

Um webhook inscrito em um ou mais eventos do Zendesk sempre envia solicitações usando o método HTTP POST. A solicitação inclui uma carga JSON que contém os dados do evento. Você não pode alterar o método HTTP ou a carga da solicitação. Para obter mais informações sobre esquemas de carga de eventos, consulte Tipos de eventos de webhook na referência da API.

Conexão a gatilhos ou automações

Se um webhook estiver conectado a um gatilho ou automação, você poderá personalizar o método HTTP, formato e conteúdo para as solicitações do webhook. Ao criar o webhook, você seleciona o método HTTP e o formato do corpo da solicitação. Os webhooks conectados a um gatilho ou uma automação são compatíveis com os estes formatos de corpo da solicitação:

JSON
xml
Conteúdo codificado do formulário

Você define o conteúdo da solicitação quando conecta o webhook ao gatilho ou automação. Para webhooks que usam o método HTTP POST, PUT ou PATCH com um formato de solicitação JSON ou XML, o conteúdo é a carga da solicitação. Webhooks que usam outros métodos ou formatos HTTP não incluem uma carga de solicitação. Em vez disso, você pode adicionar parâmetros da URL personalizados como uma matriz de duas cadeias de caracteres de valor-chave.

Ao definir a carga ou os parâmetros da URL da solicitação, você pode usar qualquer um dos placeholders de conteúdo disponíveis para inserir os dados do ticket na solicitação.

Classificação e novas tentativas do webhook

Quando um evento, um gatilho ou uma automação invoca um webhook, ela coloca a tarefa de webhook na fila de execução, mas não a executa imediatamente. Como as tarefas do webhook são executadas de maneira independente, não há garantia de que a execução vá seguir uma determinada ordem.

As solicitações do webhook serão tentadas novamente de forma automática por três vezes se o ponto de extremidade retornar alguns códigos de resposta HTTP. Diferentemente de alvos, as solicitações com falhas consecutivas não desativam webhooks. Para obter mais informações e exemplos sobre cenários de novas tentativas, consulte Gerenciamento de webhooks na documentação do desenvolvedor.

Criação de webhooks

É possível criar um webhook na Central de administração.

Como criar um webhook

Na Central de administração, clique em Aplicativos e integrações na barra lateral e selecione Webhooks > Webhooks.
Clique em Criar webhook.
- Para inscrever o webhook em um ou mais eventos do Zendesk, selecione Eventos do Zendesk e selecione um ou mais tipos na lista suspensa.
- Para conectar o webhook a um gatilho ou uma automação do Support, selecione Gatilho ou automação.
Clique em Avançar.
Insira um Nome e uma Descrição para o webhook.
Insira a URL do ponto de extremidade usada para a integração com o serviço ou sistema de terceiros. Consulte Pontos de extremidade do webhook.
Ao configurar um webhook para a integração a serviços de terceiros, consulte a documentação desse terceiro.
Selecione Método de solicitação e Formato da solicitação do webhook.
Selecione o método de Autenticação para o webhook e forneça as informações obrigatórias necessárias. Consulte Autenticação do webhook.
(Opcional) Clique em Adicionar cabeçalho para adicionar um cabeçalho personalizado e insira o Nome do cabeçalho e o Valor. Para incluir até mais quatro cabeçalhos, clique em Adicionar outro cabeçalho. Consulte Cabeçalhos personalizados de webhook.
Observação: não coloque informações confidenciais em seus cabeçalhos personalizados.
(Opcional) Clique em Testar webhook para garantir que ele esteja funcionando conforme o esperado.
Para criar o webhook, clique em Criar webhook.
Para webhooks de gatilhos e automações, você precisa conectar o webhook a um gatilho ou uma automação. Consulte Conexão de um webhook a um gatilho ou uma automação do Support. Após a conexão do gatilho ou automação, volte para a página Criar webhook e clique em Concluir configuração.

Após você criar o webhook, você pode ver os detalhes, as assinaturas e a atividade na página Webhooks na Central de administração. Consulte Gerenciamento de webhooks.

Pontos de extremidade do webhook

Os webhooks enviam solicitações para a URL do ponto de extremidade que você especifica no momento da criação deles. A URL do ponto de extremidade usa este formato: https://www.yourdomain.com/path.

Apesar de não ser obrigatório, recomendamos o uso de HTTP Seguro (HTTPS). Ao fornecer uma URL do ponto de extremidade segura, você pode ativar a autenticação e passar dados de forma segura.

Cabeçalhos personalizados de webhook

Com os cabeçalhos personalizados, é possível incluir informações adicionais na solicitação que seu webhook envia e facilitar a conexão com alguns serviços de terceiros que possuem requisitos exclusivos de cabeçalho de webhook. Os requisitos e as limitações de cabeçalhos personalizados incluem:

Para usar cabeçalhos personalizados, você precisa usar uma URL do ponto de extremidade segura (HTTPS).
Não inclua credenciais de autenticação nem outras informações confidenciais nos cabeçalhos personalizados. Em vez disso, use os métodos de autenticação aceitos.
Os nomes do cabeçalho devem ser exclusivos e não podem ter mais de 128 caracteres. Todos os caracteres US ASCII alfanuméricos são aceitos, inclusive os símbolos: !, #, $, %, &, ', *, +, -, ., ^, _, `, |, e ~.
Os valores do cabeçalho podem ter até 1.000 caracteres de comprimento e com suporte a caracteres US ASCII de 0x20 a 0x7E.

Autenticação de um webhook

Se o seu webhook está se integrando a um ponto de extremidade seguro, você tem três opções para autenticar o webhook e os dados que ele envia. Talvez seja interessante consultar a documentação de terceiros sobre os requisitos de autenticação do ponto de extremidade ou trabalhar com um desenvolvedor de sua equipe para definir o método de autenticação correto para o seu webhook.

Não é obrigatória: nenhuma autenticação é obrigatória ou está configurada.
Chave da API: usa uma chave da API para autenticar o webhook.
Autenticação básica: usa o nome de usuário e a senha para autenticar o webhook.
Token do portador: usa o token de acesso OAuth para autenticar o webhook.

Se seus desenvolvedores desejam obter mais informações sobre autenticação e segurança de webhooks, consulte a documentação sobre segurança e autenticação de webhooks.

Para reforçar a segurança, você também pode verificar a assinatura do webhook. Para obter mais informações, consulte Verifying webhook authenticity (Verificação de autenticidade do webhook).

Conexão de um webhook a um gatilho ou uma automação

Para invocar um webhook de gatilhos e automações, você primeiro precisa conectá-lo a um gatilho ou uma automação. Os gatilhos e as automações especificam as circunstâncias sob as quais o webhook deve ser invocado.

Como conectar um webhook a um gatilho do Support

Na Central de administração, clique em Objetos e regras na barra lateral e selecione Regras de negócios > Gatilhos.
Crie um novo gatilho ou edite um existente passando o cursor do mouse sobre o ícone de opções () e clicando em Editar.
Para gatilhos, em Ações, clique em Adicionar ação. Selecione Notificar webhook e escolha o seu webhook. Clique em Salvar.

Como conectar um webhook a uma automação do Support

Na Central de administração, clique em Objetos e regras na barra lateral e selecione Regras de negócios > Automações.
Crie uma nova automação ou edite uma existente passando o cursor do mouse sobre o ícone de opções () e clicando em Editar.
Para automações, em Execute estas ações:, clique no ícone de adicionar ação (). Selecione Notificações: Notificar webhook e também o seu webhook. Clique em Enviar.

Teste de um webhook

Na Central de administração, você pode testar o webhook com diferentes origens de evento e solicitações. Além de acessar os webhooks existentes especificamente para fins de teste, você também pode testar o webhook durante a criação ou a edição.

Como testar um webhook

Na Central de administração, clique em Aplicativos e integrações na barra lateral e selecione Webhooks > Webhooks.
Encontre o webhook na lista, clique no ícone de menu de opções () na linha do webhook e clique em Testar webhook.
No painel Testar webhook, selecione um evento para testar. Essa é uma solicitação de teste que você pode usar para testar a URL do ponto de extremidade.
Insira os detalhes da solicitação de teste: corpo da solicitação, parâmetros ou cabeçalhos.
Clique em Enviar teste. A resposta é exibida no painel abaixo de sua solicitação de teste.