Sending webhook notifications¶

Creating a secret for a webhook URL¶

Most webhooks require a secret or integration key in the incoming HTTP request. For example:

• When you create an incoming webhook in Slack (https://api.slack.com/messaging/webhooks#create_a_webhook), the URL for the webhook includes a secret:

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

  Copy

• When you create an incoming webhook in Teams (https://learn.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook), the URL for the webhook includes a secret:

  https://<hostname>.webhook.office.com/webhookb2/<secret>
  

  Copy

• When you set up an integration for your PagerDuty service (https://support.pagerduty.com/docs/services-and-integrations), the integration provides an integration key that you must include in webhook requests:

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

  Copy

For this secret or integration key, we recommend creating a secret object of the generic string type. This secret object is used in the following ways:

• When you create a webhook notification integration, you specify this secret object in the CREATE NOTIFICATION INTEGRATION statement.

• When you send a notification, the secret object is used to construct the HTTP request for the webhook.

Note the following:

• When you create the webhook notification integration, you must use a role that has the USAGE privilege on this secret.

• When you send a notification to this webhook, you must use a role that has the READ privilege on this secret as well as the USAGE privileges on the database and schema containing the secret.

To create this object, use the CREATE SECRET command, and specify TYPE=GENERIC_STRING. You must use a role that has the CREATE SECRET privilege on the schema where you plan to create that object.

The next sections provide examples of creating the secret object.

• Example 1: Creating a secret for a Slack webhook

• Example 2: Creating a secret for a Teams webhook

• Example 3: Creating a secret for a PagerDuty webhook

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://mymsofficehost.webhook.office.com/webhookb2/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';

Creating a webhook notification integration¶

To create a notification integration of the webhook type, use the CREATE NOTIFICATION INTEGRATION command.

When executing this command, set the following properties to set up the HTTP request that should be sent for the notification.

• Set TYPE to WEBHOOK.

• If you created a secret object for a secret to be included in the URL, HTTP request body, or header, set WEBHOOK_SECRET to the name of that secret object.

• Set WEBHOOK_URL to the URL for the webhook.

  If the webhook URL includes a secret and you created a secret object for this secret, replace the secret in the URL with SNOWFLAKE_WEBHOOK_SECRET.

• If the body of the message for the webhook needs to be in a specific format for this external system (for example, if all messages sent to this system need to use the same format), set WEBHOOK_BODY_TEMPLATE to a template for the message. In this template:

  • Use the SNOWFLAKE_WEBHOOK_SECRET placeholder where the secret should appear in the body of the message.

  • Use the SNOWFLAKE_WEBHOOK_MESSAGE placeholder where the notification message should appear.

  When you call SYSTEM$SEND_SNOWFLAKE_NOTIFICATION and pass in a message, the stored procedure uses the template to construct the body of the webhook request. The stored procedure replaces the SNOWFLAKE_WEBHOOK_MESSAGE placeholder with the message that you pass in.

• If the HTTP request to the webhook must include specific HTTP headers, set WEBHOOK_HEADERS to the list of the header names and values.

  Use the SNOWFLAKE_WEBHOOK_SECRET placeholder where the secret should appear in the value of a header.

The next sections provide examples of creating webhook notification integrations for different types of external systems.

• Example 1: Creating a notification integration for a Slack webhook

• Example 2: Creating a notification integration for a Teams webhook

• Example 3: Creating a notification integration for a PagerDuty webhook

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://mymsofficehost.webhook.office.com/webhookb2/xxxxxxxx

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

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

Sending a notification to a webhook¶

To send a notification to a webhook:

1. Pass the SANITIZE_WEBHOOK_CONTENT function to remove any placeholders (like SNOWFLAKE_WEBHOOK_SECRET) from the message.

2. Call the SYSTEM$SEND_SNOWFLAKE_NOTIFICATION stored procedure, passing in the sanitized message and specifying the name of the webhook notification integration to use.

For example, the following statement sends a JSON message to a Slack webhook, using the notification integration that you created earlier:

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

In this example, the statement passes in a message in plain text (my message). When constructing the body of the webhook request from the template specified by the WEBHOOK_BODY_TEMPLATE property of the notification integration, SYSTEM$SEND_SNOWFLAKE_NOTIFICATION replaces the SNOWFLAKE_WEBHOOK_MESSAGE placeholder with the message that you pass in.

For example, suppose that you specified the following template for the body of the request:

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

SYSTEM$SEND_SNOWFLAKE_NOTIFICATION constructs a request with the following body:

{"text": "my message"}