Webhooks

GraphCMS webhooks are a fundamental method for observing changes that happen to content within your project. Whether new content is published, or existing is updated, subscribe to these events, and get notified via a POST request to perform your own custom business logic.

For example, you could use webhooks for:

  • Syncing data to external search engine,
  • Syncing data with external PIM,
  • Redeploying your static website when content or assets change,
  • Triggering email campaigns based on new content added.
  • Push messages into Slack.

Triggers

Triggers can be configured to listen to one or more content model, stage, and action events.

Trigger
Content ModelAll models, including Asset
StageDraft, Published, and custom content stages
ActionCreate, Update, Delete, Publish, and Unpublish

Receiving a webhook

Once an event occurs, data is sent as JSON in a POST requests body to the configured URL. The contents of the request always contain the operation, and data of the event.

Each event will also contain the __typename, stage, localizations, as well as the full content entry. The id and __typename of the related entries are also included.

The snapshot of the current stage is only sent in the webhook body. This means that:

  • Create, Update, and Delete actions only send the draft version.
  • Publishing, and Unpublishing actions only send the published version.

Securing webhooks

It is best to protect the endpoints which your webhooks invoke. This prevents unauthorized actions on your server, and better protects your users from any suspicious activity.

When configuring your webhook, add an Authorization header with a secret key only your incoming webhook server knows.

When we trigger your webhook, we will also send all of the custom headers you create, including Authorization. If the values don't match, you can skip. You can think of this as a handshake between GraphCMS and your custom business logic.

Example payload

Below is an example of both DRAFT, and PUBLISHED content stage events.

In the examples below we have a Post model.

Create a webhook

  1. Navigate to Webhooks in the sidebar. Webhooks are in the lower group of icons.
  2. Press "Create" in the upper right corner of the window.
  3. Fill out the configuration for your webhook.
  4. Press "Create"

Configuration

  • A name for organzing and finding your webhooks
  • A short description to inform others what your webhook does
  • Toggle if you want to include the payload or not
  • The URL to be called
  • The content model(s) that will be watched
  • The content stage to be watched
  • The action to be watched
  • Any additional headers to pass along

Enable / Disable webhooks

  1. Navigate to Webhooks in the sidebar.
  2. Move your cursor to the title of the webhook, and click the pencil icon that appears.
  3. Switch the the "Active" toggle in the upper right corner to switch between on or off.

Delete a webhook

  1. Navigate to Webhooks in the sidebar.
  2. Move your cursor to the title of the webhook, and click the trash icon that appears.
  3. Confirm you want to delete the webhook.

Did you find this page useful?

Your feedback helps us improve our docs, and product.

This site uses cookies to provide you with a better user experience. For more information, refer to our Privacy Policy