Schema proposals notifications
Receive alerts when a schema proposal is created or revised
Schema proposals are only available with a GraphOS Enterprise plan.
Configure GraphOS to send notifications to a webhook whenever schema proposals are created or revised or if their status changes. These webhooks are useful for automating workflows. For example, your organization may want to open a draft pull request in your codebase whenever a proposal's status changes to Approved.
Setup
Go to your graph's Settings page in GraphOS Studio.
Open the Reporting tab.
Click Add notification in the upper right.
Select Schema proposal and click Next.
Select the schema proposal event(s) you want to receive notifications for:
- Proposal creation
- Proposal revision
- Proposal status change
Select either an existing webhook notification channel or to create a new one. If creating a new one, configure the webhook as described 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.
Optionally, enter a Secret Token.
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. Thex-apollo-signature
header has the formatsha256=<hmac-value>
.Refer to this guide from Okta to learn more about implementation and see additional resources.
Click Next and complete any remaining steps in the dialog.
Webhook format
Custom webhook notification details are provided as a JSON object in the request body. To avoid including sensitive information, payloads contain IDs—for example, proposal ID and revision ID—rather than objects containing details about the proposal or revision. You can use the Platform API to fetch full objects using the IDs in the webhook payload.
The JSON object conforms to the structure of the ResponseShape
interface:
enum ProposalStatus {OPENDRAFTIMPLEMENTEDAPPROVED}interface ResponseShape {"eventType": string;"eventID": string;"graphID": string;"variantID": string;"proposalID": string;"change": {"status": ProposalStatus | undefined"previousStatus": ProposalStatus | undefined"revisionId": string | undefined},"timestamp": string;}
Field descriptions
Field | Description |
---|---|
| The schema proposal event, either |
| A unique event ID |
| A unique proposal ID |
|
|
| A unique graph ID |
| An unique ID in the graph ref format, for example, |
| An ISO 8601 Date string indicating when the event occurred |