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 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, the Pipelines App needs to be installed first.

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

Releases

Caution

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

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)

Task App Webhook Configuration

Caution

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 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 application code.

Securing a Webhook

Note

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 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've inserted the secret, press Save. Storyblok will then include 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 webhook-signature was correctly generated using your secret. For step-by-step guidance, check out our tutorial: Securing Webhooks: Verifying Signatures in Different Technologies. It provides actual code examples to help you implement verification.

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.

Related resources

Webhooks in the Management API