How to use Storyblok webhooks

If 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.

Available webhooks

Published, unpublished and deleted story

Example Payloads:

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

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

{
  "action": "deleted",
  "text": "The user test@domain.com deleted 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 Pipeline Stage deployment

Requires the app "Pipeline Stages"

Example Payload:

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

Workflow Stage Changed

Example Payload:

{
    "action": "workflow_stage_changed",
    "text": "The workflow stage of story Home has been changed to Reviewing.",
    "story_id": 2270165,
    "workflow_stage_name": "Reviewing",
    "space_id": 65703
}

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

Securing your webhooks

For security reasons, you probably want to limit requests to those coming from Storyblok. This can be done by setting up a secret token and validate the information.

1. Go to the Webhook settings of your space
2. Click "Define/Edit" to define a secret. (For example by taking the output of ruby -rsecurerandom -e 'puts SecureRandom.hex(20)' in the terminal).
3. Click "Save" or hit Enter

You can now check the webhook payload signature like in the following example in Ruby on Rails. Before using this example you need to define the environment variable STORYBLOK_WEBHOOK_TOKEN with the secret defined in step 2:

class WebhookController < ApplicationController
  def create
    verify_signature(request.raw_post)
    # do stuff when verified
    render json: {success: true}
  end

  def verify_signature(payload_body)
    signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), ENV['STORYBLOK_WEBHOOK_TOKEN'], payload_body)
    raise StandardError, "Signature check failed!" unless Rack::Utils.secure_compare(signature, request.env['HTTP_WEBHOOK_SIGNATURE'])
  end
end