Notifications for budgets¶

Setting up email notification¶

To set up email notification:

1. (Optional) If you want to use your own notification integration, create a notification integration or choose an existing notification integration that you want to use. A notification integration enables Snowflake to send notifications to a third-party system.

   1. Create a notification integration with TYPE = EMAIL and ALLOWED_RECIPIENTS set to the list of verified email addresses of the recipients. For information, see Create an email notification integration and Restrict the list of email addresses that can receive notifications.

      Note

      Each email address added for budget notifications must be verified. The email notification setup fails if any email address in the list is not verified.

      For example:

      CREATE NOTIFICATION INTEGRATION budgets_notification_integration
        TYPE = EMAIL
        ENABLED = TRUE
        ALLOWED_RECIPIENTS = ('costadmin@example.com','budgetadmin@example.com');
      

      Copy

   2. Verify that the notification integration works as expected by calling the SYSTEM$SEND_SNOWFLAKE_NOTIFICATION stored procedure to send a test message.

      For example, you can send a test message in JSON format:

      CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
        SNOWFLAKE.NOTIFICATION.APPLICATION_JSON('{"name": "value"}'),
        SNOWFLAKE.NOTIFICATION.INTEGRATION('budgets_notification_integration')
      );
      

      Copy

   3. Grant the USAGE privilege on the notification integration to the SNOWFLAKE application. The USAGE privilege enables the budget to use the notification integration to send the notification. For example:

      GRANT USAGE ON INTEGRATION budgets_notification_integration
        TO APPLICATION snowflake;
      

      Copy

2. Specify the email addresses that should receive the notification. If you created or selected a notification integration to use, associate the notification integration with the budget.

   To do this, call the <budget_name>!SET_EMAIL_NOTIFICATIONS method, and specify the following:

   • If you do not have a notification integration that you want to use, pass in a comma-delimited list of verified email addresses. For example, if you are configuring notifications for the account budget:

     CALL SNOWFLAKE.LOCAL.ACCOUNT_ROOT_BUDGET!SET_EMAIL_NOTIFICATIONS(
       'costadmin@example.com, budgetadmin@example.com'
     );
     

     Copy

     If you are configuring notifications for a custom budget, call the method on the object for the custom budget. For example, if you created a custom budget named my_budget:

     CALL my_budget!SET_EMAIL_NOTIFICATIONS(
       'costadmin@example.com, budgetadmin@example.com'
     );
     

     Copy

   • If you have a notification integration that you want to use, pass in the name of that integration and a comma-delimited list of verified email addresses. For example, if you are configuring notifications for the account budget:

     CALL SNOWFLAKE.LOCAL.ACCOUNT_ROOT_BUDGET!SET_EMAIL_NOTIFICATIONS(
       'budgets_notification_integration',
       'costadmin@example.com, budgetadmin@example.com'
     );
     

     Copy

     If you are configuring notifications for a custom budget, call the method on the object for the custom budget. For example, if you created a custom budget named my_budget:

     CALL my_budget!SET_EMAIL_NOTIFICATIONS(
       'budgets_notification_integration',
       'costadmin@example.com, budgetadmin@example.com'
     );
     

     Copy

3. If you associated a notification integration with the budget, you can verify that the budget is associated with your notification integration by calling the <budget_name>!GET_NOTIFICATION_INTEGRATION_NAME method. This method returns the name of the email notification integration associated with the budget.

   For example, if you are configuring notifications for the account budget:

   CALL SNOWFLAKE.LOCAL.ACCOUNT_ROOT_BUDGET!GET_NOTIFICATION_INTEGRATION_NAME();
   

   Copy

   If you are configuring notifications for a custom budget, call the method on the object for the custom budget. For example, if you created a custom budget named my_budget:

   CALL my_budget!GET_NOTIFICATION_INTEGRATION_NAME();
   

   Copy

Setting up queue notification¶

To set up queue notification:

1. Create a notification integration or choose an existing notification integration that you want to use. A notification integration enables Snowflake to send notifications to a third-party system.

   Create a notification integration with TYPE=QUEUE, DIRECTION=OUTBOUND, and the additional properties required for the cloud provider. For information, see:

   • Creating a notification integration to send notifications to an Amazon SNS topic

   • Creating a notification integration to send notifications to a Microsoft Azure Event Grid topic

   • Creating a notification integration to send notifications to a Google Cloud Pub/Sub topic

   Note

   Your account must be on the same cloud platform as the cloud provider queue.

   For example:

   CREATE OR REPLACE NOTIFICATION INTEGRATION budgets_notification_integration
     ENABLED = TRUE
     TYPE = QUEUE
     DIRECTION = OUTBOUND
     NOTIFICATION_PROVIDER = AWS_SNS
     AWS_SNS_TOPIC_ARN = '<ARN_for_my_SNS_topic>'
     AWS_SNS_ROLE_ARN = '<ARN_for_my_IAM_role>';
   

   Copy

   Note

   For queue and webhook notifications, you can associate up to 10 notification integrations with a budget.

2. Verify that the notification integration works as expected by calling the SYSTEM$SEND_SNOWFLAKE_NOTIFICATION stored procedure to send a test message.

   For example, you can send a test message in JSON format:

   CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
     SNOWFLAKE.NOTIFICATION.APPLICATION_JSON('{"name": "value"}'),
     SNOWFLAKE.NOTIFICATION.INTEGRATION('budgets_notification_integration')
   );
   

   Copy

3. Grant the USAGE privilege on the notification integration to the SNOWFLAKE application. The USAGE privilege enables the budget to use the notification integration to send the notification. For example:

   GRANT USAGE ON INTEGRATION budgets_notification_integration
     TO APPLICATION snowflake;
   

   Copy

4. Associate the notification integration with the budget. Call the <budget_name>!ADD_NOTIFICATION_INTEGRATION method, passing in the name of the integration.

   For example, if you are configuring notifications for the account budget:

   CALL SNOWFLAKE.LOCAL.ACCOUNT_ROOT_BUDGET!ADD_NOTIFICATION_INTEGRATION(
     'budgets_notification_integration',
   );
   

   Copy

   If you are configuring notifications for a custom budget, call the method on the object for the custom budget. For example, if you created a custom budget named my_budget:

   CALL my_budget!ADD_NOTIFICATION_INTEGRATION(
     'budgets_notification_integration',
   );
   

   Copy

5. Verify that the notification integration is associated with the budget.

   Call the <budget_name>!GET_NOTIFICATION_INTEGRATIONS method to print out the list of notification integrations associated with the budget.

   For example, if you are configuring notifications for the account budget:

   CALL SNOWFLAKE.LOCAL.ACCOUNT_ROOT_BUDGET!GET_NOTIFICATION_INTEGRATIONS();
   

   Copy

   If you are configuring notifications for a custom budget, call the method on the object for the custom budget. For example, if you created a custom budget named my_budget:

   CALL my_budget!GET_NOTIFICATION_INTEGRATIONS();
   

   Copy

   The method prints out a table that lists the names of the integrations, the times that they were last used to send notifications, and the dates when they were added.

   +----------------------------------+------------------------+------------+
   |  INTEGRATION_NAME                | LAST_NOTIFICATION_TIME | ADDED_DATE |
   +----------------------------------+------------------------+------------+
   | budgets_notification_integration | -1                     | 2024-09-23 |
   +----------------------------------+------------------------+------------+
   

Setting up webhook notification¶

To set up webhook notification:

1. Create a notification integration or choose an existing notification integration that you want to use. A notification integration enables Snowflake to send notifications to a third-party system.

   Create a notification integration with TYPE=WEBHOOK and the additional properties required for the webhook. For information, see Sending webhook notifications.

   The notification message is in JSON format, so you should configure the notification integration to handle this. For example, the following statements create a secret and a notification integration for a Slack webhook:

   CREATE OR REPLACE SECRET my_database.my_schema.slack_secret
     TYPE = GENERIC_STRING
     SECRET_STRING = '... secret in my Slack webhook URL ...';
   
   CREATE OR REPLACE NOTIFICATION INTEGRATION budgets_notification_integration
     ENABLED = TRUE
     TYPE = WEBHOOK
     WEBHOOK_URL = 'https://hooks.slack.com/services/SNOWFLAKE_WEBHOOK_SECRET'
     WEBHOOK_BODY_TEMPLATE='{"text": "SNOWFLAKE_WEBHOOK_MESSAGE"}'
     WEBHOOK_HEADERS=('Content-Type'='application/json')
     WEBHOOK_SECRET = slack_secret;
   

   Copy

   Note

   For queue and webhook notifications, you can associate up to 10 notification integrations with a budget.

2. Verify that the notification integration works as expected by calling the SYSTEM$SEND_SNOWFLAKE_NOTIFICATION stored procedure to send a test message.

   For example, you can send a test message in JSON format. Make sure to escape the double quotes in the JSON string and the backslashes:

   CALL SYSTEM$SEND_SNOWFLAKE_NOTIFICATION(
     SNOWFLAKE.NOTIFICATION.APPLICATION_JSON('{\\\"name\\\": \\\"value\\\"}'),
     SNOWFLAKE.NOTIFICATION.INTEGRATION('budgets_notification_integration')
   );
   

   Copy

3. Grant the USAGE privilege on the notification integration to the SNOWFLAKE application. The USAGE privilege enables the budget to use the notification integration to send the notification. For example:

   GRANT USAGE ON INTEGRATION budgets_notification_integration
     TO APPLICATION snowflake;
   

   Copy

4. If you are using a webhook notification integration that relies on a secret, grant the following privileges to the SNOWFLAKE application.

   • The READ privilege on that secret.

   • The USAGE privilege on the schema containing that secret.

   • The USAGE privilege on the database containing that schema.

   For example:

   GRANT READ ON SECRET slack_secret TO APPLICATION snowflake;
   GRANT USAGE ON SCHEMA my_schema TO APPLICATION snowflake;
   GRANT USAGE ON DATABASE my_database TO APPLICATION snowflake;
   

   Copy

5. Associate the notification integration with the budget.

   Call the <budget_name>!ADD_NOTIFICATION_INTEGRATION method, and pass in the name of the integration.

   For example, if you are configuring notifications for the account budget:

   CALL SNOWFLAKE.LOCAL.ACCOUNT_ROOT_BUDGET!ADD_NOTIFICATION_INTEGRATION(
     'budgets_notification_integration',
   );
   

   Copy

   If you are configuring notifications for a custom budget, call the method on the object for the custom budget. For example, if you created a custom budget named my_budget:

   CALL my_budget!ADD_NOTIFICATION_INTEGRATION(
     'budgets_notification_integration',
   );
   

   Copy

6. Verify that the notification integration is associated with the budget.

   Call the <budget_name>!GET_NOTIFICATION_INTEGRATIONS method, which prints out the list of notification integrations associated with the budget.

   For example, if you are configuring notifications for the account budget:

   CALL SNOWFLAKE.LOCAL.ACCOUNT_ROOT_BUDGET!GET_NOTIFICATION_INTEGRATIONS();
   

   Copy

   If you are configuring notifications for a custom budget, call the method on the object for the custom budget. For example, if you created a custom budget named my_budget:

   CALL my_budget!GET_NOTIFICATION_INTEGRATIONS();
   

   Copy

   The method prints out a table that lists the names of the integrations, the times that they were last used to send notifications, and the dates when they were added.

   +----------------------------------+------------------------+------------+
   |  INTEGRATION_NAME                | LAST_NOTIFICATION_TIME | ADDED_DATE |
   +----------------------------------+------------------------+------------+
   | budgets_notification_integration | -1                     | 2024-09-23 |
   +----------------------------------+------------------------+------------+
   

Interpreting the JSON notification message¶

When you configure a budget to send a notification to a cloud provider queue or a webhook, the notification message contains a JSON object similar to the following:

{
  "account_name": "MY_ACCOUNT",
  "budget_name": "MY_BUDGET_NAME",
  "type": "BUDGET_LIMIT_WARNING",
  "limit": "100",
  "spending": "67.42",
  "spending_percent": "67.42",
  "spending_trend_percent": "130.63",
  "time_percent":"51.61"
}

The JSON object contains the following key-value pairs:

Checking the history of notifications for a budget¶

To view the history of notifications for a budget, call the NOTIFICATION_HISTORY function and filter on the integration name. For example:

SELECT * FROM TABLE(
  INFORMATION_SCHEMA.NOTIFICATION_HISTORY(
    INTEGRATION_NAME=>'budgets_notification_integration'
  )
);

The message_source column contains BUDGET for rows representing budget notifications.

Disabling notifications for a budget¶

To disable notifications for a budget, call the SET_NOTIFICATION_MUTE_FLAG method, and pass in TRUE as an argument. For example:

CALL SNOWFLAKE.LOCAL.ACCOUNT_ROOT_BUDGET!SET_NOTIFICATION_MUTE_FLAG(TRUE);

Removing a notification integration from a budget¶

To remove a notification integration from a budget, call the <budget_name>!REMOVE_NOTIFICATION_INTEGRATION method, passing in the name of the integration. For example:

CALL my_budget!REMOVE_NOTIFICATION_INTEGRATION(
  'budgets_notification_integration',
);