Webhooks

Webhooks

Admins podem configurar webhooks para que as pessoas possam enviar alerts para uma URL específica. Ou seja, você pode configurar um alert para enviar os resultados de uma question para o endpoint que desejar: para seu aplicativo, um serviço de terceiros ou qualquer outro lugar.

No momento, webhooks estão disponíveis apenas para alerts; não é possível selecionar um webhook como destinatário de uma dashboard subscription.

Criando um webhook

Antes de enviar um alert para um webhook, um admin precisa criar o webhook de destino.

Admins podem criar um webhook clicando no ícone de engrenagem > Admin settings > Notification channels. Na seção Webhooks for alerts, clique em + Add another. O Analytics irá apresentar um formulário simples para preencher:

• Webhook URL. Local para onde o Analytics enviará os resultados do alert. Deve ser uma URL válida.
• Dê um nome. Você deve nomear o webhook para que as pessoas possam escolher o hook correto ao configurar um alert numa question.
• Descrição. Recomenda-se informar para que serve o webhook.
• Método de autenticação. Veja abaixo.

Método de autenticação do webhook

Você pode especificar um método de autenticação para o webhook.

• None: Qualquer requisição é aceita.
• Basic: Informar nome de usuário e senha.
• Bearer: Incluir um token secreto.
• API key: Você pode adicionar a API key no Header ou como Query parameter. Ambas as formas requerem uma chave e um valor (a própria API key).

Payload do webhook

O Analytics enviará os resultados do alert em formato JSON. O JSON incluirá alguns metadados sobre a question, como o criador do alert e seu ID (null no caso de alerts de teste).

O Analytics enviará a visualização “anexada” como uma imagem PNG codificada em base64 dentro da chave data, dentro de visualization.

E os dados conforme visualizados na tabela, que o Analytics enviará como raw_data.

Aqui está um exemplo de payload para um alert (o encoding do PNG foi truncado por ser muito longo e pouco relevante):

{
  "type": "alert",
  "alert_id": null,
  "alert_creator_id": 2666,
  "alert_creator_name": "Roberto Bolaño",
  "data": {
    "type": "question",
    "question_id": 108,
    "question_name": "Sales",
    "question_url": "http://help.hellocloud.com/question/108",
    "visualization": "data:image/png;base64,=...LONG_ENCODED_PNG_HERE...",
    "raw_data": {
      "cols": [
        "CREATED_AT",
        "count"
      ],
      "rows": [
        [
          "2023-09-01T00:00:00Z",
          346
        ],
        [
          "2023-10-01T00:00:00Z",
          354
        ],
        [
          "2023-11-01T00:00:00Z",
          394
        ],
        [
          "2023-12-01T00:00:00Z",
          418
        ],
        [
          "2024-01-01T00:00:00Z",
          457
        ],
        [
          "2024-02-01T00:00:00Z",
          404
        ],
        [
          "2024-03-01T00:00:00Z",
          445
        ],
        [
          "2024-04-01T00:00:00Z",
          439
        ],
        [
          "2024-05-01T00:00:00Z",
          520
        ],
        [
          "2024-06-01T00:00:00Z",
          455
        ],
        [
          "2024-07-01T00:00:00Z",
          523
        ],
        [
          "2024-08-01T00:00:00Z",
          501
        ]
      ]
    }
  },
  "sent_at": "2024-09-30T20:16:15.76582Z"
}

Leitura adicional

• Alerts