Envio de notificações de webhook¶

Criação de um segredo para um URL de webhook¶

A maioria dos webhooks exige uma chave segredo ou de integração na solicitação HTTP. Por exemplo:

• Quando você cria um webhook de entrada no Slack, o URL do webhook inclui um segredo:

  https://hooks.slack.com/services/<secret>
  

  Copy

• Quando você cria um webhook de entrada com fluxos de trabalho para Microsoft Teams, o URL do webhook inclui um segredo:

  https://<hostname>.<region>.logic.azure.com:443/workflows/<secret>
  

  Copy

• Quando você define uma integração para seu serviço do PagerDuty, a integração fornece uma chave de integração que você deve incluir nas solicitações de webhook:

  {
     "routing_key" : "<integration_key>",
     /* ... */
  

  Copy

Para essa chave segredo ou de integração, recomendamos criar um objeto segredo do tipo genérico de cadeia de caracteres. Este objeto segredo é usado das seguintes maneiras:

• Quando você cria uma integração de notificação de webhook, você especifica esse objeto segredo na instrução CREATE NOTIFICATION INTEGRATION.

• Quando você envia uma notificação, o objeto segredo é usado para construir a solicitação HTTP do webhook.

Observe o seguinte:

• Quando você cria a integração de notificação de webhook, você deve usar uma função que tenha o privilégio USAGE para esse segredo.

• Ao enviar uma notificação para este webhook, você deve usar uma função que tenha o privilégio READ para esse segredo, bem como privilégios USAGE para o banco de dados e esquema que contém o segredo.

Para criar esse objeto, use o comando CREATE SECRET e especifique TYPE=GENERIC_STRING. Você deve usar uma função que tenha o privilégio CREATE SECRET no esquema onde planeja criar esse objeto.

As próximas seções fornecem exemplos de criação do objeto segredo.

• Exemplo 1: criando um segredo para um webhook do Slack

• Exemplo 2: criando um segredo para um fluxo de trabalho para webhook do Microsoft Teams

• Exemplo 3: criando um segredo para um webhook do PagerDuty

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

CREATE OR REPLACE SECRET my_slack_webhook_secret
  TYPE = GENERIC_STRING
  SECRET_STRING = 'T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX';

https://prod-114.westeurope.logic.azure.com:443/workflows/xxxxxxxx

CREATE OR REPLACE SECRET my_teams_webhook_secret
  TYPE = GENERIC_STRING
  SECRET_STRING = 'xxxxxxxx';

xxxxxxxx

CREATE OR REPLACE SECRET my_pagerduty_webhook_secret
  TYPE = GENERIC_STRING
  SECRET_STRING = 'xxxxxxxx';

Criação da integração de notificação de webhook¶

Para criar uma integração de notificação do tipo webhook, use o comando CREATE NOTIFICATION INTEGRATION.

Ao executar esse comando, defina as seguintes propriedades para configurar a solicitação HTTP que deve ser enviada para a notificação.

• Defina TYPE como WEBHOOK.

• Se você criou um objeto segredo para um segredo a ser incluído no URL, corpo da solicitação HTTP ou cabeçalho, defina WEBHOOK_SECRET como o nome desse objeto segredo.

• Defina WEBHOOK_URL para o URL do webhook.

  Se o URL do webhook incluir um segredo e você tiver criado um objeto segredo para esse segredo, substitua o segredo no URL por SNOWFLAKE_WEBHOOK_SECRET.

• Se o corpo da mensagem para o webhook precisar estar em um formato específico para este sistema externo (por exemplo, se todas as mensagens enviadas para esse sistema precisarem usar o mesmo formato), defina WEBHOOK_BODY_TEMPLATE para um modelo da mensagem. Neste modelo:

  • Use o espaço reservado SNOWFLAKE_WEBHOOK_SECRET onde o segredo deve aparecer no corpo da mensagem.

  • Use o espaço reservado SNOWFLAKE_WEBHOOK_MESSAGE onde a mensagem de notificação deve aparecer.

  Quando você chama SYSTEM$SEND_SNOWFLAKE_NOTIFICATION e passa uma mensagem, o procedimento armazenado usa o modelo para construir o corpo da solicitação do webhook. O procedimento armazenado substitui o espaço reservado SNOWFLAKE_WEBHOOK_MESSAGE pela mensagem que você passa.

• Se a solicitação HTTP para o webhook precisar incluir cabeçalhos HTTP específicos, defina WEBHOOK_HEADERS para a lista de nomes e valores de cabeçalho.

  Use o espaço reservado SNOWFLAKE_WEBHOOK_SECRET onde o segredo deve aparecer no valor de um cabeçalho.

As próximas seções fornecem exemplos de criação de integrações de notificação de webhook para diferentes tipos de sistemas externos.

• Exemplo 1: criando uma integração de notificação para um webhook do Slack

• Exemplo 2: criando uma integração de notificação para um webhook de fluxos de trabalho para Microsoft Teams

• Exemplo 3: criando uma integração de notificação para um webhook do PagerDuty

https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

CREATE OR REPLACE NOTIFICATION INTEGRATION my_slack_webhook_int
  TYPE=WEBHOOK
  ENABLED=TRUE
  WEBHOOK_URL='https://hooks.slack.com/services/SNOWFLAKE_WEBHOOK_SECRET'
  WEBHOOK_SECRET=my_secrets_db.my_secrets_schema.my_slack_webhook_secret
  WEBHOOK_BODY_TEMPLATE='{"text": "SNOWFLAKE_WEBHOOK_MESSAGE"}'
  WEBHOOK_HEADERS=('Content-Type'='application/json');

https://prod-114.westeurope.logic.azure.com:443/workflows/xxxxxxxx

CREATE OR REPLACE NOTIFICATION INTEGRATION my_teams_webhook_int
  TYPE=WEBHOOK
  ENABLED=TRUE
  WEBHOOK_URL='https://prod-114.westeurope.logic.azure.com/workflows/SNOWFLAKE_WEBHOOK_SECRET'
  WEBHOOK_SECRET=my_secrets_db.my_secrets_schema.my_teams_webhook_secret
  WEBHOOK_BODY_TEMPLATE='{"text": "SNOWFLAKE_WEBHOOK_MESSAGE"}'
  WEBHOOK_HEADERS=('Content-Type'='application/json');

https://events.pagerduty.com/v2/enqueue

CREATE OR REPLACE NOTIFICATION INTEGRATION my_pagerduty_webhook_int
  TYPE=WEBHOOK
  ENABLED=TRUE
  WEBHOOK_URL='https://events.pagerduty.com/v2/enqueue'
  WEBHOOK_SECRET=my_secrets_db.my_secrets_schema.my_pagerduty_webhook_secret
  WEBHOOK_BODY_TEMPLATE='{
    "routing_key": "SNOWFLAKE_WEBHOOK_SECRET",
    "event_action": "trigger",
    "payload": {
      "summary": "SNOWFLAKE_WEBHOOK_MESSAGE",
      "source": "Snowflake monitoring",
      "severity": "INFO"
    }
  }'
  WEBHOOK_HEADERS=('Content-Type'='application/json');

Enviar uma notificação para um webhook¶

Para enviar uma notificação para um webhook:

1. Passe a função SANITIZE_WEBHOOK_CONTENT para remover espaços reservados (como SNOWFLAKE_WEBHOOK_SECRET) da mensagem.

2. Chame o procedimento armazenado SYSTEM$SEND_SNOWFLAKE_NOTIFICATION, passando a mensagem higienizada e especificando o nome da integração de notificação de webhook a ser usada.

Por exemplo, a instrução a seguir envia uma mensagem JSON para um webhook do Slack, usando a integração de notificação que você criou anteriormente:

CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
  SNOWFLAKE.NOTIFICATION.TEXT_PLAIN(
    SNOWFLAKE.NOTIFICATION.SANITIZE_WEBHOOK_CONTENT('my message')
  ),
  SNOWFLAKE.NOTIFICATION.INTEGRATION('my_slack_webhook_int')
);

Neste exemplo, a instrução passa uma mensagem em texto simples (my message). Ao construir o corpo da solicitação do webhook a partir do modelo especificado pela propriedade WEBHOOK_BODY_TEMPLATE da integração de notificação, SYSTEM$SEND_SNOWFLAKE_NOTIFICATION substitui o espaço reservado SNOWFLAKE_WEBHOOK_MESSAGE pela mensagem que você passa.

Por exemplo, suponha que você especificou o seguinte modelo para o corpo da solicitação:

CREATE OR REPLACE NOTIFICATION INTEGRATION my_slack_webhook_int
  ...
  WEBHOOK_BODY_TEMPLATE='{"text": "SNOWFLAKE_WEBHOOK_MESSAGE"}'
  ...

SYSTEM$SEND_SNOWFLAKE_NOTIFICATION constrói uma solicitação com o seguinte corpo:

{"text": "my message"}