Frequently Asked Questions

Webhooks & Gatsby Cloud Integration

How can I deploy my Gatsby Cloud project automatically when content changes in Hygraph?

You can use Hygraph webhooks to automatically trigger deployments in Gatsby Cloud whenever content changes occur. By configuring a webhook in your Hygraph project to point to your Gatsby Cloud site's build webhook URL, any specified content actions (such as publish or unpublish) will initiate a new build in Gatsby Cloud. For step-by-step instructions, see the official guide.

What are the prerequisites for deploying a Gatsby Cloud project with Hygraph webhooks?

To deploy a Gatsby Cloud project using Hygraph webhooks, you need:

For more details, see the prerequisites section of the documentation.

How do I configure a webhook in Hygraph to trigger a Gatsby Cloud build?

To configure a webhook in Hygraph for Gatsby Cloud builds:

  1. In Gatsby Cloud, go to Settings > Webhook and copy your Builds Webhook URL.
  2. In your Hygraph project, navigate to Webhooks and click Add.
  3. Fill in the webhook details, including the name, description, method (POST), and paste the Builds Webhook URL.
  4. Optionally, add a secret key for payload signing and configure triggers (models, stages, actions, sources) as needed.
  5. Add any required headers, such as authentication keys.
For a detailed walkthrough, refer to the configuration guide.

What actions in Hygraph will trigger a build in Gatsby Cloud?

Any actions you configure as triggers in your Hygraph webhook (such as PUBLISH or UNPUBLISH) will trigger a build in Gatsby Cloud. For example, publishing or unpublishing content in the Hygraph Content Editor will initiate a new build. You can monitor build activity in both Hygraph's webhook logs and Gatsby Cloud's build history. See this section for more details.

How do I migrate from the deprecated Gatsby integration to using webhooks in Hygraph?

The Gatsby integration is deprecated and no longer supported. To migrate to webhooks:

  1. In your Hygraph project, go to Apps and locate your Gatsby integration card.
  2. Delete the integration by clicking the trash icon.
  3. Navigate to Webhooks and follow the configuration steps to set up a new webhook for Gatsby Cloud. See the migration guide for details.

Are webhooks in Hygraph environment-specific?

Yes, webhooks in Hygraph are environment-specific. This means that their configuration applies to each environment separately. If your project uses multiple environments, you need to configure webhooks for each one as needed. Source: Hygraph Docs.

Webhooks: General Information & Benefits

What are webhooks and how do they work in Hygraph?

Webhooks are user-defined HTTP requests that are triggered when a specific event occurs in one application, sending payload data to another system in real time. In Hygraph, webhooks can be configured to automate tasks such as triggering deployments, notifications, or integrations with other services. When a configured event (like publishing content) happens, Hygraph sends an HTTP POST request to the specified URL, enabling seamless automation and integration. Learn more about webhooks.

What are the benefits of using webhooks in web development?

Webhooks offer several benefits in web development, including:

By leveraging webhooks, developers can build more efficient and robust web applications. Source: Hygraph Blog.

Technical Requirements & Troubleshooting

What environment variables do I need to set up my Gatsby Cloud site with Hygraph?

You need to set the following environment variables in Gatsby Cloud:

These variables are required for both build and preview environments. For more details, see the setup guide.

How can I check if my webhook is triggering builds correctly in Gatsby Cloud?

You can verify that your webhook is working by:

Both logs will show if a build was triggered as expected. For more information, see the documentation.

Support & Resources

Where can I find more information or get help with Hygraph webhooks and Gatsby Cloud integration?

You can find more information in the following resources:

Security & Compliance

What security and compliance certifications does Hygraph have?

Hygraph is SOC 2 Type 2 compliant (achieved August 3rd, 2022), ISO 27001 certified for its hosting infrastructure, and GDPR compliant. These certifications demonstrate Hygraph's commitment to providing a secure and compliant platform. For more details, visit the security features page.

Help teams manage content creation and approval in a clear and structured way
Hygraph
Docs
You are currently reading the Studio Docs. If you were looking for the Classic Docs check here

#Deploy your Gatsby Cloud project with Hygraph webhooks

If you are using Gatsby Cloud for your deployments, you can use Hygraph webhooks to automatically deploy when content changes.

#Prerequisites

  • You must have a Hygraph account. If you don't have one, you can create one here.
  • You must have a Hygraph project. Read this document to access further information on how to create Hygraph projects.
  • You must have an Gatsby Cloud account. If you don't have one, you can create one here.
  • You must have a Gatsby Cloud site. Read this document to access further information on how to get started with Gatsby Cloud.

#Your Gatsby Cloud site

You can use your pre-existing Hygraph powered Gatsby site in Gatsby Cloud - if you have one - or you can create a new site by importing your pre-existing Gatsby project from a GitHub repository. You can follow this guide for instructions on how to do this.

During the setup process, you will be asked to provide the necessary environment variables for your Gatsby site to build:

Environment variables in Gatsby CloudEnvironment variables in Gatsby Cloud

You will find this information in your Hygraph project by navigating to Project settings > API access.

In HygraphIn Gatsby Cloud
Content APIHYGRAPH_ENDPOINT
Permanent Auth TokensHYGRAPH_TOKEN

You will find the Content API URL under Endpoints. Scroll down to the bottom of the screen to find the Permanent Auth Tokens.

#Configure webhooks

The first thing you need to do is navigate to your Gatsby Site, go to Settings > Webhook, and copy your Builds Webhook. Follow these steps afterwards:

  1. In Your Hygraph Project, go to Webhooks and click on the Add button, located in the upper right corner of the screen, or on the +Add Webhook button at the center of the screen.
  2. The Add webhook screen will display. Complete the following information:
    • Name: Name for your webhook.
    • Description: Description for your webhook. Optional field.
    • Include payload: Switch. True by default. If true, data will be sent via the webhook.
    • Method: Dropdown menu that allows you to select an HTTP method from a list. The default value is POST, but you can also select DELETE, GET or PUT.
    • URL: Webhook URL. This is where you paste the Builds Webhook that you copied from your Gatsby Site settings.
    • Secret key: You can optionally add a secret key to sign the payload of your webhook. The secret key allows the other end to check that the source is genuine. This can be used to verify requests and, for instance, avoid triggering deploys from unknown sources.
    • Triggers: This is where you select which Models, Stages, Actions and Sources should trigger your webhook. Each item has a dropdown menu, where you can select one or more options. Selecting none acts as a wildcard, then all models will trigger the webhook. If you're a developer, this document contains some more information on triggers that might be useful to you.
    • Headers: Here you can configure your headers by adding additional Key and Value data, then clicking on the Add button. You can add multiple key-value sets, and you can delete the ones you added by clicking on the trash icon. Some endpoints require authentication using API Keys, which could be set here.

Gatsby webhook example - HeadersGatsby webhook example - Headers

#Trigger a Gatsby Cloud build from Hygraph

Once the webhook has been configured, performing one of the trigger actions will trigger a build in Gatsby Cloud.

For instance, if the trigger actions you configured for the webhook are PUBLISH and UNPUBLISH, doing either of those actions in the Content editor will trigger a new build in Gatsby Cloud.

You will be able to check the new build in your Hygraph project by checking the logs. You can also see this in your in your Gatsby Site, under Master > Build history.

#Migrate from Gatsby integration to webhooks

Follow these steps to migrate from your Gatsby integration to webhooks:

  1. In your Hygraph project, navigate to Apps and locate your Gatsby integration card.
  2. Click on the trash icon to delete.
  3. Finally, navigate to Webhooks and follow the configuration process.

#Resources