Schema proposals notifications

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

1. Go to your graph'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 schema proposal 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 field. 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>.

   See an example

   Given the following inputs:

   Secret token (key): your_secret_token

   Request body (message):

   JSON

   1
   {
   2
     "eventType": "APOLLO_PROPOSAL_STATUS_CHANGE",
   3
     "eventId": "00000000-0000-0000-0000-00000000",
   4
     "graphId": "graphId",
   5
     "variantId": "p-1",
   6
     "proposalId": "00000000-0000-0000-0000-00000000",
   7
     "change": {
   8
       "status": "OPEN",
   9
       "previousStatus": "DRAFT"
   10
     },
   11
     "timestamp": "1970-01-01T00:00:00+0000"
   12
   }

   Copy

   Hash function: SHA256

   The x-apollo-header value would be sha256=0400670a3ea155eb9f602a60e7897e72515e1a4b04fe06a786e631cc32a1307e.

   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:

1
enum ProposalStatus {
2
  OPEN
3
  DRAFT
4
  IMPLEMENTED
5
  APPROVED
6
}
7

8
interface ResponseShape {
9
  "eventType": string;
10
  "eventID": string;
11
  "graphID": string;
12
  "variantID": string;
13
  "proposalID": string;
14
  "change": {
15
    "status": ProposalStatus | undefined
16
    "previousStatus": ProposalStatus | undefined
17
    "revisionId": string | undefined
18
  },
19
  "timestamp": string;
20
}

Field descriptions