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, open Settings → Webhooks and click + 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 (for example, published or updated) to trigger the webhook.

Webhook example triggers and payloads

Story

Event Name	Description
published	A story is published
unpublished	A story is unpublished
deleted	A story is deleted
moved	A story is moved

Datasource

Event Name	Description
entries_updated	A datasource entry is saved or added
datasource_entry_saved	A datasource entry is saved or added (legacy webhook)

Asset

Event Name	Description
created	An asset is uploaded
replaced	An asset is replaced
deleted	An asset is deleted
restored	An asset is restored

User management

Event Name	Description
added	A user is added to the space
removed	A user is removed from the space
roles_updated	A user role is updated

Workflow

Event Name	Description
stage.changed	The workflow stage of a story changed
workflow_stage_changed	The workflow stage of a story changed (legacy webhook)

Discussion

Event Name	Description
created	A discussion is created
comment_created	A comment added in the discussion
comment_updated	A comment updated
comment_deleted	A comment deleted
resolved	A discussion is resolved

Pipeline

Caution

To use pipeline webhooks, install the Pipelines App.

Event Name	Description
deployed	A pipeline stage is deployed
branch_deployed	A pipeline stage is deployed (legacy webhook)

Releases

Caution

To use release webhooks, install the Releases App.

Event Name	Description
merged	A release is merged into the current released content
release_merged	A release is merged into the current released content (legacy webhook)

Tasks

Caution

To use task webhooks, install the Tasks App.

The Tasks App allows you to create automation tasks that trigger webhooks when 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 Name	Description
task_execution	Trigger a request from Storyblok
task_execution	With 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"
    }
}

Note

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 project's code.

Secure a webhook

Note

Refer to our pricing plans to check if your account supports webhook secrets.

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 randomly generated string with at least 20 characters for your webhook secret. You can generate one using the following command:

openssl rand -hex 20

Once you save the secret, Storyblok includes a signature in every webhook request. The signature is sent in the webhook-signature header. If no secret is set, this header remains empty.

To verify webhook requests, your endpoint should check if the secret generated the correct webhook-signature. For a step-by-step guide, follow our tutorial: Securing Webhooks: Verifying Signatures in Different Technologies. It provides actual code examples to help you implement verification.

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

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 don't retry on failure. Retrying could cause issues, as Publish and Save are single events. For long-running tasks, respond immediately (for example, 202 Accepted) to avoid timeouts after 120 seconds.

Related resources

Webhooks in the Management API