Os desenvolvedores da web normalmente usam webhooks para invocar um comportamento em outro sistema. Por exemplo, você pode usar webhooks para:
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.
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, no usuário, na disponibilidade do agente, na central de ajuda ou na 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.
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
-
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 os parâmetros de URL ou a carga de solicitação, você pode usar qualquer um dos placeholders de conteúdo disponíveis para inserir os dados do ticket na solicitação.
Os parâmetros de URL ou a carga de solicitação do webhook precisam ser inferiores a 256 KB.
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 Ações e 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 de evento na lista suspensa.
- Para conectar o webhook a um gatilho ou uma automação do Support, selecione Gatilho ou automação.
- Clique em Next.
- 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.
- Os cabeçalhos a seguir não têm suporte:
- accept-charset
- accept-encoding
- connection
- content-encoding
- content-length
- content-md5
- content-type
- date
- expect
- forwarded
- host
- keep-alive
- max-forwards
- origem
- proxy-authenticate
- referer
- server
- te
- trailer
- transfer-encoding
- upgrade
- user-agent
- via
- www-authenticate
- zendesk-api-version
- zendesk-ep
- Além disso, os cabeçalhos não podem começar com os prefixos a seguir:
- access-control
- x-amzn
- x-apigw
- x-datadog
- x-envoy
- x-forwarded
- x-zendesk
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. - Em Ações, clique em Adicionar ação. Selecione Notificar webhook e escolha o seu webhook.
- Insira os parâmetros de URL ou a carga de solicitação do webhook, dependendo do formato de solicitação do webhook. A carga ou os parâmetros precisam ser inferiores a 256 KB.
- Clique em Salvar.
- 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.
- Em Execute estas ações:, clique no ícone de adicionar ação (
). Selecione Notificações: Notificar webhook e também o seu webhook. - Insira os parâmetros de URL ou a carga de solicitação do webhook, dependendo do formato de solicitação do webhook. A carga ou os parâmetros precisam ser inferiores a 256 KB.
- 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 Ações e 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.