Join us from October 8-10 in New York City to learn the latest tips, trends, and news about GraphQL Federation and API platform engineering.Join us for GraphQL Summit 2024 in NYC
Start for Free

Schema proposals notifications

Receive alerts when a schema proposal is created or revised

are only available with a GraphOS Enterprise plan.

Configure to send notifications to a webhook whenever 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.


  1. Go to your 's Settings page in GraphOS Studio.

  2. Open the Reporting tab.

  3. Click Add notification in the upper right.

  4. Select Schema proposal and click Next.

  5. Select the event(s) you want to receive notifications for:

    • Proposal creation
    • Proposal revision
    • Proposal status change
  6. 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.

  1. Specify a name for this notification channel in the Channel Name . This name must be unique among all your graph's notification channels, including Slack channels.

  2. In the Webhook URL input, provide the URL of your HTTP(S) endpoint.

  3. 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. The x-apollo-signature header has the format sha256=<hmac-value>.

    Refer to this guide from Okta to learn more about implementation and see additional resources.

  4. 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 {
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




A unique event ID


A unique proposal ID

  • This field isn't present for APOLLO_PROPOSAL_CREATED events.

  • For PROPOSAL_REVISION_SAVED events, the unique revisionID of the saved revision.

  • For APOLLO_PROPOSAL_STATUS_CHANGE events, the current status and previousStatus of the proposal. See proposal statuses for more information.


A unique graph ID


An unique ID in the format, for example, graphID@variantName


An ISO 8601 Date string indicating when the event occurred

Schema changes
Performance alerts
Rate articleRateEdit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc., d/b/a Apollo GraphQL.

Privacy Policy