> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/pt/sonar/administration/settings/webhooks.md).

# Webhooks

Settings › Web Hooks define requisições HTTP, com método, URL, cabeçalhos e um corpo JSON com variáveis, que um modelo de alerta envia quando um alerta é disparado ou resolvido.

## O que é e quando usar

Um webhook é uma requisição HTTP que o SONAR envia a outro sistema quando um alerta é disparado ou resolvido: uma mensagem em um canal de chat, um chamado na sua central de atendimento, um evento na sua plataforma de monitoramento. Você define a requisição uma vez em **Admin Center › Settings › Web Hooks**, com variáveis para o alerta, o dispositivo, o cliente e o site, e depois a escolhe em um modelo de alerta como ação de falha, ação de resolução, ou as duas.

Use um webhook quando o e-mail e o SMS não são onde a sua equipe trabalha, ou quando outro sistema precisa registrar o alerta.

Ao contrário de uma ação de URL, que o seu navegador abre, um webhook é enviado pelo próprio SONAR. Veja [Ações de URL](https://wiki.datadike.com/pt/sonar/administration/settings/url-actions.md) para a diferença.

## Antes de começar

* Para listar e testar webhooks, seu papel precisa de **Run URL Actions** (grupo **System** em **Admin Center › Roles**). A mesma permissão preenche as listas de webhooks do formulário do modelo de alerta.
* Para adicioná-los, editá-los ou excluí-los, seu papel também precisa de **View Core Settings** e **Edit Core Settings** (grupo **Settings**).
* Para associar um webhook a um modelo de alerta, seu papel precisa de **Manage Alert Templates** (grupo **Alerts**).
* O destino precisa aceitar requisições vindas do SONAR. Se ele filtra pelo endereço de origem, peça ao suporte de implementação da DataDike o endereço a partir do qual o SONAR envia.
* A URL de destino, o método que ela espera e os cabeçalhos de que ela precisa, como um token de autorização emitido por esse sistema.

## Passos

### Adicionar um webhook

1. Abra **Admin Center › Settings** e a aba **Web Hooks**.
2. Clique em **Add Web Hook**.
3. Digite um **Name** e, se quiser, uma **Description**.
4. Digite o **URL Pattern**, o endereço para onde vai a requisição. Ele pode conter variáveis.
5. Escolha o **Method**: **GET**, **POST**, **PUT**, **DELETE** ou **PATCH**.
6. Em **Request Body**, escreva o corpo JSON, com as variáveis dentro das cadeias de caracteres. A aba fica indisponível para **GET** e **DELETE**.
7. Em **Request Headers**, escreva os cabeçalhos como um objeto JSON.
8. Clique em **Test** para experimentar a requisição; veja abaixo.
9. Clique em **Submit**.

Um corpo para um serviço de chat poderia ser assim:

```json
{
  "text": "{{alert.severity}} on {{agent.hostname}} ({{client.name}} / {{site.name}}): {{alert.message}}"
}
```

e os cabeçalhos assim, com o token emitido por esse serviço guardado no repositório de chaves:

```json
{
  "Content-Type": "application/json",
  "Authorization": "Bearer {{global.CHAT_TOKEN}}"
}
```

### Testar um webhook

1. Em **Add Web Hook** ou **Edit Web Hook**, clique em **Test**.
2. Em **Testing NAME**, escolha contra o que executá-lo: **Agent**, **Site**, **Client** ou **None**, e selecione o dispositivo, o site ou o cliente.
3. Clique em **Run**.

O SONAR envia a requisição e mostra a **URL** e o **Body** que enviou, com as variáveis preenchidas, e a **Response** que recebeu. Com **None**, nenhuma variável é preenchida. As variáveis `{{alert...}}` só recebem valores quando o webhook é executado para um alerta real.

### Usar em um modelo de alerta

1. Abra o modelo de alerta; veja [Alertas e modelos de alerta](https://wiki.datadike.com/pt/sonar/administration/automation/alerts.md).
2. Na etapa **Alert Actions**, em **Alert Failure Settings**, escolha **Send a Web Hook** e selecione o webhook em **Failure Web Hook**.
3. Em **Alert Resolved Settings**, escolha **Send a Web Hook** e selecione o webhook em **Resolved Web Hook**, se o outro sistema também precisar saber que o alerta terminou.
4. Em **Run actions only on**, deixe ligados os tipos de alerta que devem enviá-lo: **Agents** (dispositivo em atraso), **Checks**, **Tasks**.
5. Salve o modelo.

## O que você deve ver

O quadro **Web Hooks for Alert Failure/Resolved Actions** lista cada webhook com **Name**, **Description** e **URL Pattern**; sem nenhum, ele mostra **No Web Hooks added yet.**

Para cada alerta de um dispositivo que usa o modelo, o SONAR envia o webhook de falha uma vez, quando o alerta é disparado, e o webhook de resolução uma vez, quando o alerta se resolve sozinho porque o check, a tarefa ou o dispositivo voltou ao normal. Resolver um alerta manualmente em **Alerts** não envia o webhook de resolução. O webhook de resolução só é enviado quando a ação de falha do modelo também é **Send a Web Hook**. Uma entrega que falhou não é repetida.

Os alertas informativos e de aviso só enviam webhooks se **Informational Alerts** e **Warning Alerts** estiverem marcados em **Admin Center › Settings › General**; veja [Configurações gerais](https://wiki.datadike.com/pt/sonar/administration/settings/general.md).

## Como verificar se funcionou

1. Clique em **Test**, execute-o contra um dispositivo de teste e confira se **Response** traz a resposta que você espera do outro sistema, e se a mensagem, o chamado ou o evento aparece lá.
2. Faça um check falhar em um dispositivo de teste cujo modelo de alerta envia o webhook.
3. Abra **Alerts**, encontre o alerta e clique no botão **Show failure action run results**. O resultado mostra o código de status HTTP que o outro sistema devolveu e a resposta dele.
4. Os testes aparecem em **Reports & Audits › Audits** sob a ação **URL Action**; veja [Trilha de auditoria](https://wiki.datadike.com/pt/sonar/administration/audit/audit-trail.md).

## Erros comuns

| Sintoma                                                                           | Causa                                                                                                                                                                                | Correção                                                                                                                                                      |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Response** informa um erro de conexão                                           | URL errada, ou o destino não aceita requisições vindas do SONAR                                                                                                                      | Confira a URL; peça ao suporte de implementação da DataDike o endereço a partir do qual o SONAR envia                                                         |
| **Response** traz um erro de autenticação do outro sistema                        | Falta um cabeçalho, ou o token dele está errado                                                                                                                                      | Confira **Request Headers**, e o valor no repositório de chaves se o token estiver guardado lá                                                                |
| O outro sistema rejeita o corpo                                                   | O corpo não é um JSON válido, ou não está no formato que esse sistema espera                                                                                                         | Corrija o JSON e compare-o com a documentação do outro sistema                                                                                                |
| `None` aparece na URL ou no corpo                                                 | A variável não tem valor para esse dispositivo ou alerta, ou o repositório de chaves não tem nenhuma chave com esse nome                                                             | Confira o valor no dispositivo e os nomes das chaves; veja [Variáveis de script](https://wiki.datadike.com/pt/sonar/reference/script-variables.md)            |
| O nome do dispositivo, do cliente ou do site aparece onde se esperava outro valor | O nome da variável está grafado errado, ou o campo personalizado não existe: nesse caso o SONAR coloca o nome do objeto                                                              | Confira os nomes das variáveis                                                                                                                                |
| O outro sistema recebe o corpo inteiro como uma única string de texto             | Um valor com aspas duplas, muitas vezes em `{{alert.message}}`, tornou o corpo um JSON inválido, e o SONAR o enviou como string                                                      | Mantenha `{{alert.message}}` em campos descritivos, e use identificadores como `{{alert.id}}` nos campos que o outro sistema usa para correlacionar registros |
| **Failed to save** com uma mensagem sobre um campo em branco                      | **Name** ou **URL Pattern** está vazio                                                                                                                                               | Preencha os dois                                                                                                                                              |
| **Failed to load actions**, ou a lista **Failure Web Hook** está vazia            | O papel não tem **Run URL Actions**                                                                                                                                                  | Conceda essa permissão em **Admin Center › Roles**                                                                                                            |
| O teste funciona, mas os alertas não enviam nada                                  | O modelo não se aplica ao dispositivo, o tipo de alerta está desligado em **Run actions only on**, ou a severidade do alerta está desligada em **Admin Center › Settings › General** | Confira os três pontos; veja [Alertas e modelos de alerta](https://wiki.datadike.com/pt/sonar/administration/automation/alerts.md)                            |

## Referência de campos

### Webhook

| Campo               | O que faz                              | Valores aceitos                                            | Padrão                                 |
| ------------------- | -------------------------------------- | ---------------------------------------------------------- | -------------------------------------- |
| **Name**            | Rótulo na lista e no modelo de alerta  | Texto. Obrigatório                                         | Vazio                                  |
| **Description**     | Nota para os outros administradores    | Texto                                                      | Vazio                                  |
| **URL Pattern**     | Endereço para onde vai a requisição    | Uma URL completa, com variáveis se necessário. Obrigatório | Vazio                                  |
| **Method**          | Método HTTP                            | **GET**, **POST**, **PUT**, **DELETE**, **PATCH**          | **POST**                               |
| **Request Body**    | Corpo da requisição, enviado como JSON | Um documento JSON. Não usado com **GET** e **DELETE**      | `{ }`                                  |
| **Request Headers** | Cabeçalhos da requisição               | Um objeto JSON com nomes e valores de cabeçalhos           | `{"Content-Type": "application/json"}` |

Para **POST**, **PUT** e **PATCH**, o SONAR espera até 8 segundos pela resposta.

### Variáveis

| Variável                                                | Substituída por                                                                                                                                           |
| ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{{alert.id}}`                                          | O número do alerta. Use-o para correlacionar e fechar o registro no outro sistema                                                                         |
| `{{alert.message}}`                                     | A mensagem do alerta, que cita o dispositivo e o check ou a tarefa que falhou                                                                             |
| `{{alert.severity}}`                                    | `error`, `warning` ou `info`                                                                                                                              |
| `{{alert.alert_type}}`                                  | O tipo de alerta: `availability` (dispositivo em atraso), `check` ou `task`                                                                               |
| `{{alert.alert_time}}`                                  | Quando o alerta foi disparado                                                                                                                             |
| `{{alert.resolved_on}}`                                 | Quando o alerta foi resolvido, para o webhook de resolução                                                                                                |
| `{{agent.hostname}}`                                    | O nome do dispositivo                                                                                                                                     |
| `{{agent.agent_id}}`                                    | O identificador estável do dispositivo, o `agent_id` da [API](https://wiki.datadike.com/pt/sonar/reference/api.md)                                        |
| `{{client.name}}`, `{{site.name}}`                      | O cliente e o site aos quais o dispositivo pertence                                                                                                       |
| `{{agent.FIELD}}`, `{{client.FIELD}}`, `{{site.FIELD}}` | O valor do campo personalizado chamado `FIELD`; veja [Campos personalizados](https://wiki.datadike.com/pt/sonar/administration/settings/custom-fields.md) |
| `{{global.NAME}}`                                       | O valor da chave `NAME`; veja [Repositório de chaves](https://wiki.datadike.com/pt/sonar/administration/settings/key-store.md)                            |

A lista completa está em [Variáveis de script](https://wiki.datadike.com/pt/sonar/reference/script-variables.md).

## Páginas relacionadas

* [Alertas e modelos de alerta](https://wiki.datadike.com/pt/sonar/administration/automation/alerts.md): onde os webhooks são associados
* [Ações de URL](https://wiki.datadike.com/pt/sonar/administration/settings/url-actions.md): links abertos pelo seu navegador
* [Repositório de chaves](https://wiki.datadike.com/pt/sonar/administration/settings/key-store.md): mantenha os tokens fora do próprio webhook
* [Notificações por e-mail e SMS](https://wiki.datadike.com/pt/sonar/administration/settings/email-and-sms.md): os outros canais de notificação
* [Variáveis de script](https://wiki.datadike.com/pt/sonar/reference/script-variables.md): todas as variáveis que você pode usar
