Webhooks

A webhook lets one application send information to another. In Storyblok, webhooks notify external services about events: a story published, an asset uploaded, a user removed, a discussion created, and more.

Your application (or any other external service) can then initiate automated tasks, such as clearing the cache or triggering build processes.

Set up webhooks

To configure a webhook in Storyblok:

In your space, open Settings → Webhooks and select + New Webhook.
Enter the Endpoint URL that handles the payload.
In paid plans, add a Webhook secret for verification.
Select one or more events that trigger the webhook.

To generate a random 20-character secret with OpenSSL, run the following command in the terminal, and copy the output:

openssl rand -hex 20

// Example output
// a4eabf7836aab21c6239e3db67b4681c17a8eb87

Webhook triggers and example payloads

Storyblok provides triggers for events related to stories, assets, workflows, user management, data sources, discussions, experiments, and the Releases and Pipelines apps.

Storyblok dashboard showing a "New Webhook" configuration modal with fields for name, description, endpoint URL, secret, and trigger options. — Create a new webhook or edit an existing one.

Each trigger runs when performing actions either in the app or via the API, and provides a payload with matching properties:

Universal fields: all payloads include text, action, and space_id properties.
Entity-specific fields: each trigger also includes its own properties. For example, story_id, asset_id, workflow_name, user_id, datasource_slug, and so on.

The following events are available as triggers when creating a new webhook.

Story

Action name	Description
`published`	A user published a story
`unpublished`	A user unpublished a story
`deleted`	A user deleted a story
`moved`	A user moved a story to another folder

[
  {
    "trigger": "story.published",
    "payload": {
      "text": "The user joy.bringer@storyblok.com published the Story Home 2 (marketing-articles/home-2)\nhttps://app.storyblok.com/#/me/spaces/184738/stories/0/0/166888799188279",
      "action": "published",
      "space_id": 184738,
      "story_id": 166888799188279,
      "full_slug": "marketing-articles/home-2"
    }
  },
  {
    "trigger": "story.unpublished",
    "payload": {
      "text": "The user joy.bringer@storyblok.com unpublished the Story Home 2 (marketing-articles/home-2)\nhttps://app.storyblok.com/#/me/spaces/184738/stories/0/0/166888799188279",
      "action": "unpublished",
      "space_id": 184738,
      "story_id": 166888799188279,
      "full_slug": "marketing-articles/home-2"
    }
  },
  {
    "trigger": "story.deleted",
    "payload": {
      "text": "The user joy.bringer@storyblok.com deleted the Story 2 (2)\nhttps://app.storyblok.com/#/me/spaces/184738/stories/0/0/166887004517421",
      "action": "deleted",
      "space_id": 184738,
      "story_id": 166887004517421,
      "full_slug": "2"
    }
  },
  {
    "trigger": "story.moved",
    "payload": {
      "text": "The user joy.bringer@storyblok.com moved the Story Home 2 (marketing-articles/home-2)\nhttps://app.storyblok.com/#/me/spaces/184738/stories/0/0/166888799188279",
      "action": "moved",
      "space_id": 184738,
      "story_id": 166888799188279,
      "full_slug": "marketing-articles/home-2",
      "old_full_slug": "home-2"
    }
  }
]

Asset

Action name	Description
`created`	A user uploaded an asset
`replaced`	A user replaced an asset
`deleted`	A user deleted an asset
`restored`	A user restored a deleted asset

[
  {
    "trigger": "asset.created",
    "payload": {
      "text": "The user joy.bringer@storyblok.com created the Asset asdasdas.jpeg\nhttps://a.storyblok.com/f/184738/2048x1366/4a5ba99420/asdasdas.jpeg",
      "action": "created",
      "asset_id": 166889582905517,
      "space_id": 184738
    }
  },
  {
    "trigger": "asset.replaced",
    "payload": {
      "text": "The user joy.bringer@storyblok.com replaced the Asset asdasdas.jpeg\nhttps://a.storyblok.com/f/184738/2048x1366/4a5ba99420/asdasdas.jpeg",
      "action": "replaced",
      "asset_id": 166889582905517,
      "space_id": 184738
    }
  },
  {
    "trigger": "asset.deleted",
    "payload": {
      "text": "The user joy.bringer@storyblok.com deleted the Asset my-test-asset.webp\nhttps://a.storyblok.com/f/184738/ca28f3e327/my-test-asset.webp",
      "action": "deleted",
      "asset_id": 141684807612387,
      "space_id": 184738
    }
  },
  {
    "trigger": "asset.restored",
    "payload": {
      "text": "The user joy.bringer@storyblok.com restored the Asset my-test-asset.webp\nhttps://a.storyblok.com/f/184738/ca28f3e327/my-test-asset.webp",
      "action": "restored",
      "asset_id": 141684807612387,
      "space_id": 184738
    }
  }
]

Workflow

Event Name	Description
`stage.changed`	A user changed a story's workflow stage

[
  {
    "trigger": "stage.changed",
    "payload": {
      "text": "The workflow stage of story Home has been changed to Drafting.",
      "action": "stage.changed",
      "space_id": 184738,
      "story_id": 153831606405117,
      "workflow_name": "Default",
      "workflow_stage_name": "Drafting"
    }
  }
]

User management

Action name	Description
`added`	An admin added a user to the space
`removed`	An admin removed a user from the space
`roles_updated`	An admin updated a user's role

[
  {
    "trigger": "user.added",
    "payload": {
      "text": "The user joy.bringer@storyblok.com was added by joy.bringer@storyblok.com",
      "action": "added",
      "user_id": 110860,
      "space_id": 184738
    }
  },
  {
    "trigger": "user.removed",
    "payload": {
      "text": "The user joy.bringer@storyblok.com was removed by joy.bringer@storyblok.com",
      "action": "removed",
      "user_id": 110860,
      "space_id": 184738
    }
  },
  {
    "trigger": "user.roles_updated",
    "payload": {
      "text": "The user joy.bringer@storyblok.com roles were updated by joy.bringer@storyblok.com",
      "action": "roles_updated",
      "user_id": 110860,
      "space_id": 184738
    }
  }
]

Datasource

Action name	Description
`entries_updated`	A user saved or added a datasource
`entries_deleted`	A user deleted a datasource entry

[
  {
    "trigger": "datasource.entries_updated",
    "payload": {
      "text": "The datasource entry test has been saved.",
      "action": "entries_updated",
      "space_id": 184738,
      "datasource_slug": "background-color-options"
    }
  },
  {
    "trigger": "datasource.entries_deleted",
    "payload": {
      "text": "The datasource entry Test 1 has been deleted.",
      "action": "entries_deleted",
      "space_id": 184738,
      "datasource_slug": "test"
    }
  }
]

Discussion

Action name	Description
`created`	A user created a discussion
`resolved`	A user resolved a discussion
`comment_created`	A user added a comment to a discussion
`comment_deleted`	A user deleted a comment
`comment_updated`	A user updated a comment

[
  {
    "trigger": "discussion.created",
    "payload": {
      "id": 166895941348171,
      "lang": "default",
      "text": "user joy.bringer@storyblok.com:Test test, Discussion created on Story: Home \nhttps://app.storyblok.com//#/me/spaces/184738/stories/0/0/153831606405117?discussionId=166895941348171",
      "title": "Body",
      "action": "created",
      "space_id": 184738,
      "story_id": 153831606405117,
      "block_uid": "a9e71780-2114-4860-8d0f-e72a726d627c",
      "component": "page",
      "fieldname": "body"
    }
  },
  {
    "trigger": "discussion.resolved",
    "payload": {
      "id": 166890710530888,
      "lang": "default",
      "text": "user joy.bringer@storyblok.com:hello, Discussion resolved on Story: Home \nhttps://app.storyblok.com//#/me/spaces/184738/stories/0/0/153831606405117?discussionId=166890710530888",
      "title": "Body",
      "action": "resolved",
      "space_id": 184738,
      "story_id": 153831606405117,
      "block_uid": "a9e71780-2114-4860-8d0f-e72a726d627c",
      "component": "page",
      "fieldname": "body"
    }
  },
  {
    "trigger": "discussion.comment_created",
    "payload": {
      "id": 166895941348171,
      "lang": "default",
      "text": "user joy.bringer@storyblok.com:test , Discussion comment_created on Story: Home \nhttps://app.storyblok.com//#/me/spaces/184738/stories/0/0/153831606405117?discussionId=166895941348171",
      "title": "Body",
      "action": "comment_created",
      "space_id": 184738,
      "story_id": 153831606405117,
      "block_uid": "a9e71780-2114-4860-8d0f-e72a726d627c",
      "component": "page",
      "fieldname": "body"
    }
  },
  {
    "trigger": "discussion.comment_deleted",
    "payload": {
      "id": 166894687697738,
      "lang": "default",
      "text": "user joy.bringer@storyblok.com:Hello 23213, Discussion comment_deleted on Story: Home \nhttps://app.storyblok.com//#/me/spaces/184738/stories/0/0/153831606405117?discussionId=166894687697738",
      "title": "Name Translatable",
      "action": "comment_deleted",
      "space_id": 184738,
      "story_id": 153831606405117,
      "block_uid": "226b329a-8330-4bce-8890-b879ebf3419e",
      "component": "feature",
      "fieldname": "name_translatable"
    }
  },
  {
    "trigger": "discussion.comment_updated",
    "payload": {
      "id": 166894687697738,
      "lang": "default",
      "text": "user joy.bringer@storyblok.com:Hello 23213, Discussion comment_updated on Story: Home \nhttps://app.storyblok.com//#/me/spaces/184738/stories/0/0/153831606405117?discussionId=166894687697738",
      "title": "Name Translatable",
      "action": "comment_updated",
      "space_id": 184738,
      "story_id": 153831606405117,
      "block_uid": "226b329a-8330-4bce-8890-b879ebf3419e",
      "component": "feature",
      "fieldname": "name_translatable"
    }
  }
]

Experiment

To use experiment webhooks, enable the Experiments feature in Settings → Labs.

Action name	Description
`experiment.created`	A user created an experiment
`experiment.started`	A user started an experiment
`experiment.resumed`	A user resumed an experiment
`experiment.paused`	A user paused an experiment
`experiment.completed`	A user marked an experiment as completed
`experiment.winner_selected`	A user chose an experiment's winning variant
`experiment.deleted`	A user deleted an experiment

[
  {
    "trigger": "experiment.created",
    "payload": {
      "text": "user joy.bringer@storyblok.com created the experiment A simple experiment",
      "action": "experiment.created",
      "status": "draft",
      "space_id": 292476528754160,
      "experiment_id": 176070002766742
    }
  },
  {
    "trigger": "experiment.started",
    "payload": {
      "text": "user joy.bringer@storyblok.com started the experiment A simple experiment",
      "action": "experiment.started",
      "status": "running",
      "space_id": 292476528754160,
      "experiment_id": 176070002766742
    }
  },
  {
    "trigger": "experiment.paused",
    "payload": {
      "text": "user joy.bringer@storyblok.com paused the experiment A simple experiment",
      "action": "experiment.paused",
      "status": "paused",
      "space_id": 292476528754160,
      "experiment_id": 176070002766742
    }
  },
  {
    "trigger": "experiment.resumed",
    "payload": {
      "text": "user joy.bringer@storyblok.com resumed the experiment A simple experiment",
      "action": "experiment.resumed",
      "status": "running",
      "space_id": 292476528754160,
      "experiment_id": 176070002766742
    }
  },
  {
    "trigger": "experiment.winner_selected",
    "payload": {
      "text": "user joy.bringer@storyblok.com selected a winner for the experiment A simple experiment",
      "action": "experiment.winner_selected",
      "status": "completed",
      "space_id": 292476528754160,
      "experiment_id": 176070002766742
    }
  },
  {
    "trigger": "experiment.completed",
    "payload": {
      "text": "user joy.bringer@storyblok.com completed the experiment A simple experiment",
      "action": "experiment.completed",
      "status": "completed",
      "space_id": 292476528754160,
      "experiment_id": 176070002766742
    }
  },
  {
    "trigger": "experiment.deleted",
    "payload": {
      "text": "user joy.bringer@storyblok.com deleted the experiment A simple experiment",
      "action": "experiment.deleted",
      "status": "completed",
      "space_id": 292476528754160,
      "experiment_id": 176070002766742
    }
  }
]

Releases

To use release webhooks, install the Releases app.

Action name	Description
`merged`	A release was published

[
  {
    "trigger": "release.merged",
    "payload": {
      "text": "The release Test has been merged.",
      "action": "merged",
      "space_id": 184738,
      "release_id": 166891358857247
    }
  }
]

Pipelines

To use pipeline webhooks, install the Pipelines app.

Action name	Description
`deployed`	A user deployed a pipeline stage

[
  {
    "trigger": "pipeline.deployed",
    "payload": {
      "text": "The branch Staging has been deployed.",
      "action": "deployed",
      "space_id": 184738,
      "branch_id": 101770473635025
    }
  }
]

Manual triggers with the Tasks app

The Tasks app (opens in a new window) lets you send requests to an endpoint and manually trigger actions on an external service.

To track requests sent using the Tasks app, open Settings → Webhook Logs and select the relevant Task Triggered Hook.

Action name	Description
`task_execution`	A user executed a task

{
  "task": {
    "id": "123",
    "name": "Trigger Webhook"
  },
  "text": "The user joy.bringer@storyblok.com executed the task Test",
  "action": "task_execution",
  "space_id": "292476528754160",
  "dialog_values": {
    "name": "Test"
  },
}

Secure your webhooks

Storyblok helps you protect your webhooks and ensure requests originate from trustworthy sources.

Verify `webhook-signature`

Every webhook request includes a webhook-signature header, which you can use to verify that incoming requests to your endpoint originate only from Storyblok. Once you add a Webhook secret, validate it against the signature included in the payload.

Task-based webhooks don't support secrets. To verify the payload, pass a secret key in the User dialog field and validate it in your application.

Your endpoint must check if the secret generated the correct webhook-signature. Follow the tutorial Securing Webhooks: Verifying Signatures in Different Technologies (opens in a new window) for JavaScript and Ruby code samples.

Allow Storyblok static IP addresses

To prevent unauthorized third-party access to your webhooks, use an allowlist that restricts which IP addresses can interact with them.

Storyblok maintains static IPs for most regions. Add both the primary and fallback IPs for your space’s region to the allowlist:

Region	Primary IP	Fallback IP
European Union (EU)	3.121.25.244	35.159.255.4
United States (US)	44.206.118.25	3.231.44.46
Canada (CA)	15.157.6.14	35.183.66.204
Australia (AP)	13.238.72.230	52.63.91.95
China	N/A	N/A

Troubleshoot webhooks

To troubleshoot problems with webhooks, try the following steps:

Webhooks logs: Open Settings → Webhooks, and select View logs of the relevant webhook. The logs provide detailed information on each run, including its status, JSON response, and payload.
Debug: Test and inspect a webhook request in a controlled environment. Third-party services, such as webhook.site or RequestBin, can help analyze and debug responses.
Bypass timeouts: to prevent potential issues, webhooks don’t retry on failure. To avoid timeouts for tasks that run longer than 120 seconds, respond immediately with a 202 Accepted status code (opens in a new window).

Webhooks in the Management API

Was this page helpful?

This site uses reCAPTCHA and Google's Privacy Policy (opens in a new window) . Terms of Service (opens in a new window) apply.

Get in touch with the Storyblok community