Envio de notificações de webhook

Você pode integrar as notificações do Snowflake com os seguintes sistemas externos usando os webhooks que esses sistemas fornecem:

Nota

O Snowflake não envia notificações de webhook para sistemas externos além dos listados acima.

Para enviar uma notificação para um desses sistemas:

  1. Crie o segredo para o URL do webhook para o sistema externo.

  2. Crie a integração de notificação do webhook para o sistema externo.

  3. Envie a notificação para o sistema externo, usando a integração de notificação de webhook.

As próximas seções fornecem mais detalhes sobre como definir e enviar notificações para esses sistemas externos.

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:

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

Suponha que você queira enviar notificações para um webhook do Slack com o URL:

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

Neste exemplo, o URL do webhook contém o segredo T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX.

Execute a seguinte instrução para criar um objeto segredo para este segredo:

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

Exemplo 2: criando um segredo para um webhook do Teams

Suponha que você queira enviar notificações para um webhook do Teams com o URL:

https://mymsofficehost.webhook.office.com/webhookb2/xxxxxxxx
Copy

Neste exemplo, o URL do webhook contém o segredo xxxxxxxx.

Execute a seguinte instrução para criar um objeto segredo para este segredo:

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

Exemplo 3: criando um segredo para um webhook do PagerDuty

Suponha que você queira enviar notificações para um webhook do PagerDuty e que sua chave de integração (o valor que você deve incluir no campo routing_key nas solicitações) seja:

xxxxxxxx
Copy

Execute a seguinte instrução para criar um objeto segredo para este segredo:

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

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

Suponha que você queira enviar notificações para um webhook do Slack com o URL:

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

Suponha que você criou um objeto segredo chamado my_slack_webhook_secret para o segredo T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX que aparece no URL.

Execute a seguinte instrução para criar uma integração de notificação para este webhook:

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');
Copy

Exemplo 2: criando uma integração de notificação para um webhook do Teams

Suponha que você queira enviar notificações para um webhook do Teams com o URL:

https://mymsofficehost.webhook.office.com/webhookb2/xxxxxxxx
Copy

Suponha que você criou um objeto segredo chamado my_teams_webhook_secret para o segredo xxxxxx que aparece no URL.

Execute a seguinte instrução para criar uma integração de notificação para este webhook:

CREATE OR REPLACE NOTIFICATION INTEGRATION my_teams_webhook_int
  TYPE=WEBHOOK
  ENABLED=TRUE
  WEBHOOK_URL='https://mymsofficehost.webhook.office.com/webhookb2/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');
Copy

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

Suponha que você queira enviar notificações para um webhook do PagerDuty com o URL:

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

Suponha que você criou um objeto segredo chamado my_pagerduty_webhook_secret para a chave de integração xxxxxx que deve ser incluída no campo routing_key no corpo da mensagem.

Execute a seguinte instrução para criar uma integração de notificação para este webhook:

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');
Copy

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')
);
Copy

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"}'
  ...
Copy

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

{"text": "my message"}
Copy