EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
Build Status Notifications
Receive webhook alerts whenever GraphOS attempts to build a new supergraph schema
Configure GraphOS to send notifications to a webhook whenever GraphOS attempts to build a new supergraph schema for your federated graph. Notifications indicate whether the build succeeded. Successful build notifications include a temporary URL to the new supergraph schema.
Setup
- Go to your graph's Settings page in GraphOS Studio.
- Open the Reporting tab.
- Click Add notification in the upper right.
- Select Build Status and click Next.
- In the dropdown, select which graph variant you want to receive notifications for.
- Select either an existing notification channel or select which type of new channel you want to configure. Click Next.
- If you're configuring a new channel, complete the steps in the next section.
Configure webhook
Custom webhooks require you to set up an HTTPS endpoint accessible via
the public internet. GraphOS sends webhook notifications to this
endpoint as POST requests. Notification details are
provided as JSON in the request body, as described in the next section.
Specify a name for this notification channel in the Channel Name field. This name must be unique among all your graph's notification channels, including Slack channels.
In the Webhook URL input, provide the URL of your HTTP(S) endpoint.
Click Next and complete any remaining steps in the dialog.
Secret token
Optionally, enter a Secret Token when configuring your webhook channel.
If you enter a token, each notification HTTP request includes an x-apollo-signature header whose value is a Hash Message Authentication Code (HMAC) generated using the token, the request body as the message, and the SHA256 hash function. The x-apollo-signature header has the format sha256=<hmac-value>.
The HMAC is computed over the exact bytes of the request body, which is minified JSON with no extra whitespace. When verifying the signature, make sure to use the raw request body rather than a re-serialized version.
- Secret token (key):
your_secret_token - Request body (message):
1{
2 "eventID": "00000000-0000-0000-0000-000000000000",
3 "eventType": "BUILD_PUBLISH_EVENT",
4 "graphID": "my-graph",
5 "variantID": "my-graph@current",
6 "timestamp": "1970-01-01T00:00:00+0000",
7 "buildSucceeded": true,
8 "supergraphSchemaURL": "https://graphql.api.apollographql.com/schema-link?token=00000000000000000000000000000000"
9}- Hash function: SHA256
x-apollo-signature header value would be sha256=8136e3d9a1a82d10baa05110422236615c76f3ba961cdeece41727e9889ba2c4.Refer to this guide from Okta to learn more about implementation and see additional resources.
Webhook format
Custom webhook notification details are provided as a JSON object in the request body.
The JSON object conforms to the structure of the ResponseShape interface:
1interface BuildError {
2 message: string;
3 locations: ReadonlyArray<Location>;
4}
5
6interface Location {
7 line: number;
8 column: number;
9}
10
11interface ResponseShape {
12 eventType: 'BUILD_PUBLISH_EVENT';
13 eventID: string;
14 supergraphSchemaURL: string | undefined;
15 buildSucceeded: boolean;
16 buildErrors: BuildError[] | undefined;
17 graphID: string;
18 variantID: string;
19 timestamp: string;
20}Field descriptions
| Field | Description |
|---|---|
| The build status event name; currently, always BUILD_PUBLISH_EVENT |
| A unique event ID |
| If the build succeeded, a short-lived (24-hour) URL that enables you to fetch the supergraph schema without authenticating (such as with an API key).If the build fails, this field isn't present. |
| Whether or not the build succeeded |
| If the build failed, an array of builderError objects that describe the errors that occurred during the build.If the build succeeded, this field isn't present. |
| A unique graph ID |
| An unique ID in the graph ref format graphID@variantName |
| An ISO 8601 Date string indicating when the event occurred |