Storyblok
Search Storyblok's Documentation
  1. Webhooks

Webhooks

A webhook allows one application to send information to another. In Storyblok, webhooks notify external services of events, such as when content is published or updated. This is useful for tasks like clearing caches or triggering build processes.

The receiving service must respond with a 2xx status code and Content-Type: application/json.

Setup

To configure a webhook in Storyblok:

  1. In your space, go to Settings > Webhooks and click Add new Webhook.
  2. Enter the target URL to handle the payload.
  3. (Optional) If supported by your pricing plan, add a webhook secret for verification.
  4. Select the event types (e.g., published, updated) to trigger the webhook.

Webhook example triggers and payloads

Story

Event NameDescription
publishedA story is published
unpublishedA story is unpublished
deletedA story is deleted
movedA story is moved

Datasource

Event NameDescription
entries_updatedA datasource entry is saved or added
datasource_entry_savedA datasource entry is saved or added (legacy webhook)

Asset

Event NameDescription
createdAn asset is uploaded
replacedAn asset is replaced
deletedAn asset is deleted
restoredAn asset is restored

User management

Event NameDescription
addedA user is added to the space
removedA user is removed from the space
roles_updatedA user role is updated

Workflow

Event NameDescription
stage.changedThe workflow stage of a story changed
workflow_stage_changedThe workflow stage of a story changed (legacy webhook)

Discussion

Event NameDescription
createdA discussion is created
comment_createdA comment added in the discussion
comment_updatedA comment updated
comment_deletedA comment deleted
resolvedA discussion is resolved

Pipeline

To use pipeline webhooks, the Pipelines App needs to be installed first.

Event NameDescription
deployedA pipeline stage is deployed
branch_deployedA pipeline stage is deployed (legacy webhook)

Releases

To use release webhooks, the Releases App needs to be installed first.

Event NameDescription
mergedA release is merged into the current released content
release_mergedA release is merged into the current released content (legacy webhook)

Task App Webhook Configuration

To use task webhooks, the Tasks App needs to be installed.

The Tasks App allows you to create automation tasks that trigger webhooks by clicking the Execute button. To configure a webhook, create a new task.

You can pass user inputs as dialog_values, which will be sent as the payload.

Event NameDescription
task_executionTrigger a request from Storyblok
task_executionWith user dialog: the payload contains additional data in dialog_values
Example Payload
{
    "task": {
        "id": 123,
        "name": "Trigger Webhook"
    },
    "text": "The user test@domain.com executed the task Trigger Webhook",
    "action": "task_execution",
    "space_id": 123,
    "dialog_values": {
        "name": "Test",
        "environment": "dev"
    }
}

There’s no default option to add a webhook secret to verify task webhook payloads. However, you can pass a secret key via the user input dialog and verify it in your application code.

Securing a Webhook

Check out our plans to see if webhook secrets is available for your account.

Ensuring your requests come only from trustworthy sources can help safeguard your applications. You can protect your webhooks by verifying they were triggered by Storyblok events. The sender of the webhook can be verified by validating the signature sent along with the payload and generated with a shared secret key (webhook secret).

Define Webhook secret

We recommend using a random string with at least 20 characters (e.g., the output of this command openssl rand -hex 20). Once the secret is inserted, press the Save button. Storyblok will add a signature to every webhook request once the secret is configured. The signature is sent in the webhook-signature header of the request. If the webhook secret is not set, the header remains empty.

In your webhook endpoint, you can now check if the webhook-signature was generated with the webhook secret.

Troubleshooting webhooks

To quickly identify issues with webhooks, you can use two effective strategies. First, check the Webhook Logs available in your webhook settings. These logs allow you to view detailed information about each request, including the JSON payload, by clicking on a specific log item. Second, consider using external tools like webhook.site or RequestBin to test and inspect webhook request data in a controlled environment. These tools can help you analyze and debug webhook interactions more effectively.

Errors

Webhooks aren’t retried on failure. Retrying could cause issues, as publish/save are single events. For long-running tasks, respond immediately (e.g., 202 - Accepted) to avoid timeouts after 120 seconds.