Criação de webhooks

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 ou atividade do usuário. 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.

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

1. Na Central de administração, clique em Aplicativos e integrações na barra lateral e selecione Webhooks > Webhooks.
2. 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.
3. Clique em Avançar.
4. Selecione o método de conexão do webhook.
5. Configure o webhook para integração com o serviço de terceiros ou o sistema. Para obter mais informações, consulte Pontos de extremidades de webhook e Autenticação de seu webhook.

   ao configurar um webhook para se integrar a serviços de terceiros, consulte a documentação desse terceiro.

6. (Opcional) Clique em Testar webhook para garantir que ele esteja funcionando conforme o esperado.
7. Para criar o webhook, clique em Criar webhook.
8. 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.

Autenticação do 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.
• 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.

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

1. Na Central de administração, clique em Objetos e regras na barra lateral e selecione Regras de negócios > Gatilhos.
2. Crie um novo gatilho ou edite um existente passando o cursor do mouse sobre o ícone de opções () e clicando em Editar.
3. 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

1. Na Central de administração, clique em Objetos e regras na barra lateral e selecione Regras de negócios > Automações.
2. Crie uma nova automação ou edite uma existente passando o cursor do mouse sobre o ícone de opções () e clicando em Editar.
3. 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

1. Na Central de administração, clique em Aplicativos e integrações na barra lateral e selecione Webhooks > Webhooks.
2. Encontre o webhook na lista, clique no ícone de menu de opções () na linha do webhook e clique em Testar webhook.
3. 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.
4. Insira os detalhes da solicitação de teste: corpo da solicitação, parâmetros ou cabeçalhos.
5. Clique em Enviar teste. A resposta é exibida no painel abaixo de sua solicitação de teste.