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:
- In your space, go to Settings > Webhooks and click Add new Webhook.
- Enter the target URL to handle the payload.
- (Optional) If supported by your pricing plan, add a webhook secret for verification.
- 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
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
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
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 |
{
"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 randomly generated string with at least 20 characters for your webhook secret. You can generate one using the following command:
openssl rand -hex 20Once 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.