Envoi de notifications webhook¶

Création d’un secret pour une URL webhook¶

La plupart des webhooks nécessitent une clé secrète ou d’intégration dans la requête HTTP entrante. Par exemple :

• Quand vous créez un webhook entrant dans Slack, l’URL du webhook inclut un secret :

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

  Copy

• Quand vous créez un webhook entrant dans Teams, l’URL du webhook inclut un secret :

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

  Copy

• Quand vous configurez une intégration pour votre PagerDuty service, l’intégration fournit une clé d’intégration que vous devez inclure dans les requêtes webhook :

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

  Copy

Pour cette clé secrète ou d’intégration, nous vous recommandons de créer un objet secret de type chaîne générique. Cet objet secret est utilisé des manières suivantes :

• Lorsque vous créez une intégration de notification webhook, vous spécifiez cet objet secret dans l’instruction CREATE NOTIFICATION INTEGRATION.

• Lorsque vous envoyez une notification, l’objet secret est utilisé pour construire la requête HTTP du webhook.

Remarques :

• Lorsque vous créez l’intégration de notification webhook, vous devez utiliser un rôle doté du privilège USAGE sur ce secret.

• Lorsque vous envoyez une notification à ce webhook, vous devez utiliser un rôle doté du privilège READ sur ce secret ainsi que les privilèges USAGE sur la base de données et le schéma contenant le secret.

Pour créer cet objet, utilisez la commande CREATE SECRET et spécifiez TYPE=GENERIC_STRING. Vous devez utiliser un rôle qui a le privilège CREATE SECRET sur le schéma où vous prévoyez de créer cet objet.

Les sections suivantes fournissent des exemples de création de l’objet secret.

• Exemple 1 : créer un secret pour un webhook Slack

• Exemple 2 : créer un secret pour un webhook Teams

• Exemple 3 : créer un secret pour un webhook 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://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';

Création d’une intégration de notification webhook¶

Pour créer une intégration de notification de type webhook, utilisez la commande CREATE NOTIFICATION INTEGRATION.

Lors de l’exécution de cette commande, définissez les propriétés suivantes pour configurer la requête HTTP qui doit être envoyée pour la notification.

• Définissez TYPE sur WEBHOOK.

• Si vous avez créé un objet secret pour qu’un secret soit inclus dans l’URL, le corps de la requête HTTP ou l’en-tête, attribuez à WEBHOOK_SECRET le nom de cet objet secret.

• Définissez WEBHOOK_URL sur l’URL du webhook.

  Si l’URL du webhook inclut un secret et que vous avez créé un objet secret pour ce secret, remplacez le secret dans l’URL avec SNOWFLAKE_WEBHOOK_SECRET.

• Si le corps du message du webhook doit être dans un format spécifique pour ce système externe (par exemple, si tous les messages envoyés à ce système doivent utiliser le même format), définissez WEBHOOK_BODY_TEMPLATE sur un modèle pour le message. Dans ce modèle :

  • Utilisez le caractère de remplacement SNOWFLAKE_WEBHOOK_SECRET où le secret doit apparaître dans le corps du message.

  • Utilisez le caractère de remplacement SNOWFLAKE_WEBHOOK_MESSAGE où le message de notification doit apparaître.

  Quand vous appellez SYSTEM$SEND_SNOWFLAKE_NOTIFICATION et transmettez un message, la procédure stockée utilise le modèle pour construire le corps de la requête webhook. La procédure stockée remplace l’espace réservé SNOWFLAKE_WEBHOOK_MESSAGE avec le message que vous transmettez.

• Si la requête HTTP adressée au webhook doit inclure des en-têtes HTTP spécifiques, attribuez à WEBHOOK_HEADERS la liste des noms et valeurs des en-têtes.

  Utilisez le caractère de remplacement SNOWFLAKE_WEBHOOK_SECRET où le secret doit apparaître dans la valeur d’un en-tête.

Les sections suivantes fournissent des exemples de création d’intégrations de notifications webhook pour différents types de systèmes externes.

• Exemple 1 : création d’une intégration de notification pour un webhook Slack

• Exemple 2 : création d’une intégration de notification pour un webhook Teams

• Exemple 3 : création d’une intégration de notification pour un webhook 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://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');

Envoi d’une notification à un webhook¶

Pour envoyer une notification à un webhook :

1. Transmettez la fonction SANITIZE_WEBHOOK_CONTENT permettant de supprimer tous les caractères de remplacement (comme SNOWFLAKE_WEBHOOK_SECRET) du message.

2. Appelez la procédure stockée SYSTEM$SEND_SNOWFLAKE_NOTIFICATION, transmettant le message nettoyé et spécifiant le nom de l’intégration de notification webhook à utiliser.

Par exemple, l’instruction suivante envoie un message JSON à un webhook Slack, en utilisant l’intégration de notification que vous avez créée précédemment :

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

Dans cet exemple, l’instruction transmet un message en texte brut (my message). Lors de la construction du corps de la requête webhook à partir du modèle spécifié par la propriété WEBHOOK_BODY_TEMPLATE de l’intégration de notification, SYSTEM$SEND_SNOWFLAKE_NOTIFICATION remplace le caractère de remplacement SNOWFLAKE_WEBHOOK_MESSAGE avec le message que vous transmettez.

Par exemple, supposons que vous ayez spécifié le modèle suivant pour le corps de la requête :

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

SYSTEM$SEND_SNOWFLAKE_NOTIFICATION construit une requête avec le corps suivant :

{"text": "my message"}