Setting up GraphOS notifications

GraphOS can notify your team about changes to your graph and its performance. These notifications help you stay up to date and address issues as they arise.

If you don't have a GraphOS organization yet, you can get started here.

Supported notifications and channels

GraphOS can send your team the following notification types:

• Daily reports of your graph's request rate, error rate, and latency
• Schema change notifications whenever your graph's schema is updated
• Performance alerts whenever a metric such as error percentage or request latency exceeds a particular threshold (this experimental feature requires a paid plan)
• Build status notifications whenever Apollo attempts to compose a supergraph schema for your federated graph (this preview feature is enterprise only)

Currently, GraphOS can send each of these notification types to the channel(s) indicated:

Creating a notification

1. Go to your graph's Settings page in GraphOS Studio.
2. Select the Reporting tab.
3. Click Add notification in the upper right:
4. Select a notification type and click Next:
5. In the dropdown, select which variant of your graph you want to receive notifications for.
6. Select an existing configured channel to send notifications to, or select which type of new channel you want to configure:
7. Click Next.
8. If you're configuring a new channel, complete the steps in Configuring a new channel.
9. If you're creating a daily report, select a time zone. The report is sent daily at 9 AM in the selected time zone.

Configuring a new channel

You create new channels as part of the notification creation process. The information you provide to Studio depends on the type of channel:

• Slack
• PagerDuty
• Custom webhooks (enterprise only)

After you configure a channel for your organization, you can use it to send any notification type that the channel supports. You can add any number of notification channels to your organization.

Slack

To set up Slack notifications, you first configure an incoming webhook in Slack, then provide that webhook's URL to GraphOS Studio.

1. Create an incoming Slack hook

To create an incoming Slack hook:

1. From the Incoming Hooks page of the Slack App Directory, sign in and click Add to Slack.
2. Select the Slack channel that should receive Studio notifications and click Add Incoming WebHooks integration.
3. Copy the Webhook URL (has the format https://hooks.slack.com/services/...) for use in the next step.

You can repeat this process to create webhook URLs for different Slack channels.

2. Provide the Slack hook to Studio

1. Back in Studio, specify a name for this notification channel in the Channel Name field. This name must be unique among your graph's notification channels.

   This name does not have to match the name of the Slack channel, but it's recommended for simplicity.

2. In the Slack Webhook URL field, paste the webhook URL you obtained in Create an incoming Slack hook.

3. Click Next.

4. After you complete configuration, verify that your Slack channel receives a confirmation notification from Studio.

To configure multiple Slack channels, repeat this process with a different corresponding webhook URL each time.

PagerDuty

1. Create a PagerDuty integration key

Generate an integration key for the service that should receive alerts in PagerDuty. You can select an existing service that corresponds to your GraphQL API or Add New Service.

Existing services

1. Navigate to the service's Integrations tab and click new integration.
2. Enter an Integration Name, (for example "Apollo Alerts").
3. Under "Integration type," choose Use our API directly and Events API v2.
4. Click Add Integration.
5. From the Integrations tab, copy the generated integration key from the table for use in the next step.

Adding a service

1. Under "Integration Settings," choose Use our API directly and use Events API v2.
2. Enter an Integration Name (for example, Apollo Alerts) and complete the add service flow.
3. From the Integrations tab, copy the generated integration key from the table for use in the next step.

2. Provide the integration key to Studio

1. Back in Studio, specify a name for this notification channel in the Channel Name field. This name must be unique among your graph's notification channels.

   This name does not have to match the name of the PagerDuty service, but it's recommended for simplicity.

2. In the PagerDuty Integration Key field, paste the integration key you obtained in Create a PagerDuty integration key.

3. Click Done.

Custom webhooks (enterprise only)

Custom webhooks require you to set up an HTTPS endpoint that is accessible via the public internet. Webhook notifications are sent to this endpoint as POST requests. Notification details are provided as JSON in the request body, as described in Webhook format.

1. Specify a name for this notification channel in the Channel Name field. This name must be unique among of your graph's notification channels.
2. In the Webhook URL field, provide the URL of your HTTP(S) endpoint.
3. Click Next and complete any remaining steps in the dialog.