How to use Storyblok webhooks

If you you want to trigger an action like cache clearing, or you want to start a build process when new content gets published, you’ll need a webhook.

We have a webhook which you can configure in the space settings under “Published Story Webhook”. Whenever new content gets published, Storyblok will send a POST request with story_id as a JSON payload. It expects to receive a 2xx status and Content-Type: application/json as response.

Webhooks will not be retried as they are single events on publish and / or save. If your endpoint returns something that is not of status 2xx an email will be sent to the owner of the space with a message that the webhook failed.

If you’re doing heavy lifting we recommend to use an immediate 202- Accepted response on the webhook so you will not face the 120 seconds timeout error message.

Example

Available webhooks

Published & unpublished story

Example Payload:

{
  "action": "published",
  "text": "The user test@domain.com published the Story XYZ (xyz)",
  "story_id": 123,
  "space_id": 123
}

Release Merged

requires the app “Releases”

Example Payload:

{
  "action": "release_merged",
  "text": "The release Summer Sales has been merged.",
  "release_id": 123,
  "space_id": 123
}

Completed branch deployment

Requires the app “Branches”

Example Payload:

{
  "action": "branch_deployed",
  "text": "The branch Live has been deployed.",
  "branch_id": 123,
  "space_id": 123
}

If you need to listen to other events check out the events documentation of the Storyblok Bridge.