What are Webhooks?

Webhooks are a powerful concept that enable you to execute your own business logic when an event occurs. Or in more plain terms, they are the secret messengers of the internet, connecting information between many different platforms. There are three main parts to a webhook:

  • Trigger: An action that signals that information needs to be sent.
  • Destination: The URL Where the information gets sent.
  • Payload: The information/data that gets sent.

Webhooks are available starting from the Basic Plan. New Projects can be started in a two-week trial, where you get access to higher-tier features like Webhooks, Content Localization and more.

Setting up a Webhook in GraphCMS

Creating a webhook in GraphCMS is a straight-forward process. Navigate to the Webhooks panel in the application sidebar and click the Create button in the upper right corner. From there, you'll fill out the following form fields:

Webhook Interface

1. Name Give your webhook a name for future reference.

2. Description (optional) Help yourself and others know what the webhook does by giving it a memorable description.

3. Scope Choose between MINIMAL and EXTENDED. Minimal is ideal for build hooks, for example to Netlify or Github, as it sends the minimal amount of data needed. Extended is sending the full body of what was provided to the executing mutation. We'll compare results later in this documentation.

4. URL Define what URL should be requested by the webhook. This will be the external URL from a destination such as Netlify or a debugger utility such as RequestBin.

5. Headers (optional) Define the key and value pairs for which header values your URL will expect. If you are working with authenticated APIs, this is where you would add that data.

Currently webhooks are global in GraphCMS. The trigger is any content action such as create, save, update, etc. We are working on granular controls for webhooks. Stay up-to-date on granular webhooks here.

This is only half of the equation though, you'll need to hook up the destination! Check out the webhooks landing page for inspiration on how to do this including setting up Netlify build hooks with GraphCMS.

Once created, you can inspect the status of your webhook from the Webhook Dashboard where you can edit existing details, toggle it's active/inactive state or remove the webhook entirely.

A Created Webhook

Comparing Scope Payloads

When creating a webhook you have the opportunity to choose the scope of payload data sent. The two options are Minimal or Extended.

Webhook Payload Scope

Minimal

The minimal payload is great for time-stamping activities or situations where all you want to do is touch a remote service without sending expensive data across the wire.

{
  "projectIdentifier": "cjubekk561n9a01gh4sievp2i",
  "stageName": "master",
  "info": {
    "executedAt": "2019-10-10T12:23:24.196Z",
    "operation": "mutation",
    "fieldName": "updateBodenseeSchedule"
  },
  "kind": "MINIMAL"
}

Extended

The extended payload gives you much more data where you could not only glean information from the payload itself, but you would have enough data to create followup activity with the ID of the object changed and more.

{
  "projectIdentifier": "cjubekk561n9a01gh4sievp2i",
  "stageName": "master",
  "info": {
    "args": {
      "data": {
        "status": "PUBLISHED",
        "time": "2019-09-06T06:00:00.000Z",
        "item": "Breakfast \u0026 Registration",
        "subitem": null,
        "icon": { "connect": { "id": "cjuvcudimb3d80c15jawj1u5r" } }
      },
      "where": { "id": "cjwiyto1614le0910xdctnqw5" }
    },
    "fieldName": "updateBodenseeSchedule",
    "operation": "mutation",
    "variableValues": {
      "icon": { "connect": { "id": "cjuvcudimb3d80c15jawj1u5r" } },
      "item": "Breakfast \u0026 Registration",
      "subitem": null,
      "time": "2019-09-06T06:00:00.000Z",
      "id": "cjwiyto1614le0910xdctnqw5",
      "status": "PUBLISHED"
    },
    "responseData": {
      "createdAt": "2019-06-05T08:23:54.858Z",
      "id": "cjwiyto1614le0910xdctnqw5",
      "icon": {
        "status": "PUBLISHED",
        "updatedAt": "2019-04-24T15:12:32.690Z",
        "createdAt": "2019-04-24T15:10:11.950Z",
        "id": "cjuvcudimb3d80c15jawj1u5r",
        "handle": "IWEaOvPTGqtLU4Ij4Uvb",
        "fileName": "coffee.svg",
        "height": 0,
        "width": 0,
        "size": 3603,
        "mimeType": "image/svg+xml",
        "__typename": "Asset"
      },
      "item": "Breakfast \u0026 Registration",
      "status": "PUBLISHED",
      "subitem": null,
      "time": "2019-09-06T06:00:00.000Z",
      "updatedAt": "2019-10-10T12:28:03.975Z",
      "__typename": "BodenseeSchedule"
    },
    "executedAt": "2019-10-10T12:28:04.002Z"
  },
  "kind": "EXTENDED"
}

Headers

With each webhook sent, the headers look as follows:

host              en60wr2u3fv7d.x.pipedream.net
accept-encoding   gzip
content-type      application/json
customkey         Custom Value # <-- Your header values
user-agent        Go-http-client/1.1
content-length    1183
connection        keep-alive