---
title: Webhooks
description: Discover Storyblok's documentation with comprehensive developer guides, user manuals, API references, and examples to help you get the most out of the headless CMS platform.
url: https://storyblok.com/docs/concepts/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`.

> [!NOTE]
> Webhooks can only be configured by owners and admins.

## 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](https://www.storyblok.com/pricing), 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**

> [!WARNING]
> To use pipeline webhooks, install the [Pipelines App](https://www.storyblok.com/apps/branches).

| Event Name | Description |
| --- | --- |
| deployed | A pipeline stage is deployed |
| branch\_deployed | A pipeline stage is deployed (legacy webhook) |

### **Releases**

> [!WARNING]
> To use release webhooks, install the [Releases App](https://www.storyblok.com/apps/releases_only).

| 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

> [!WARNING]
> To use task webhooks, install the [Tasks App](https://www.storyblok.com/apps/tasks).

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

```json
{
    "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](https://www.storyblok.com/pricing) 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:

```bash
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**](https://www.storyblok.com/tp/webhook-secret-with-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](http://webhook.site/) or [RequestBin,](https://pipedream.com/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](https://www.storyblok.com/docs/api/management/webhooks)

## Pagination

-   [Previous: Visual Editor](/docs/concepts/visual-editor)