Skip to content

Webhooks

Fully configurable webhooks can be useful for integrating with build pipelines to transform your content into its final form.

Beyond just triggering external services, webhooks has the facility for the external service to provide updates to the platform. This would be useful for notifying when a build is complete or if something has gone wrong.

An example where web hooks would be useful

My content drives a GatsbyJS powered website that is built and deployed by a service such as Netlify/Appveyor/etc.

A webhook can be configured to trigger the build process.

The build process can then send feedback when the process completes - either successfully or with problems.

Creating a webhook

Media can be uploaded by navigating to the "Webhooks" section from the top navbar.

Start by clicking on the "New webhook" button.

The required properties of a webhook are -

  • Name is a user-friendly short description of the webhooks purpose
  • Url is the HTTPS (or HTTP) endpoint that will be called by the webhook
  • Method is the HTTP request method the webhook will be invoked with

The optional properties are -

  • Headers are any additional HTTP headers to send along with the webhook
  • Payload is the raw body of the HTTP request to be sent with the webhook. See below for more information regarding the webhook payload.

After filling out at least the required properties, click "Save changes".

You'll now have a webhook that can be triggered.

Payload

The webhook payload is the raw body of the HTTP request sent with the webhook. You need to ensure that you add the appropriate header to the webhook configuration to ensure this is sent correctly.

Info

If the payload is a JSON object, you would want to add the Content-Type header of application/json

A special value can be inserted into the payload that will be replaced when the webhook is triggered.

$CALLBACK_URL will be replaced with the URL of an API endpoint that can be used to report back the status of the webhook.

Callback

Calling the $CALLBACK_URL will track in the system the progress of the process triggered by a webhook. The endpoint accepts a JSON object in the following format.

{
  "level": "info|warning|error",
  "message": "...",
  "status": "success|failure"
}
  • level is the log level of information being provided
  • message can be any string with information relating to the status
  • status (optional) is used to flag the webhook run as a success or failure

Triggering a webhook

You can trigger a webhook by clicking the "Trigger" button on the webhook information page.

Alternatively, you can trigger a webhook by clicking the "Trigger" button on the webhook menu.

Webhook status

After triggering a webhook, you can view the status of its run by clicking through to it from the webhook screen.

The log will show any information provided via the callback, as well as the option to update the status of the run.