From d12a31b8551c77c6a2ac4069d1d779507d9d2867 Mon Sep 17 00:00:00 2001 From: Jannik Zschiesche Date: Tue, 18 Feb 2025 12:59:58 +0100 Subject: [PATCH 1/3] Remove obsolete config --- babel.config.js | 3 --- 1 file changed, 3 deletions(-) delete mode 100644 babel.config.js diff --git a/babel.config.js b/babel.config.js deleted file mode 100644 index e00595d..0000000 --- a/babel.config.js +++ /dev/null @@ -1,3 +0,0 @@ -module.exports = { - presets: [require.resolve('@docusaurus/core/lib/babel/preset')], -}; From 561f7ffbe70193ed0f57d0329088a9c24b372fd5 Mon Sep 17 00:00:00 2001 From: Jannik Zschiesche Date: Tue, 18 Feb 2025 13:00:10 +0100 Subject: [PATCH 2/3] Ignore blog warnings --- docusaurus.config.js | 1 + 1 file changed, 1 insertion(+) diff --git a/docusaurus.config.js b/docusaurus.config.js index 132f91b..d84225b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -49,6 +49,7 @@ const config = { keywords: ['best-practice'], extendDefaults: true, }, + onUntruncatedBlogPosts: 'ignore', }, theme: { customCss: require.resolve('./assets/scss/custom.scss'), From 953a0f4090d9fa4df4055a6cb97b7dcac3f3fbb9 Mon Sep 17 00:00:00 2001 From: Jannik Zschiesche Date: Tue, 18 Feb 2025 13:00:16 +0100 Subject: [PATCH 3/3] Update storyblok documentation --- blog/2025-02-18-storyblok-webhooks.mdx | 11 +++ docs/php/symfony/storyblok/index.mdx | 13 +++ docs/php/symfony/storyblok/webhook.mdx | 129 +++++++++++++++++++++++++ 3 files changed, 153 insertions(+) create mode 100644 blog/2025-02-18-storyblok-webhooks.mdx create mode 100644 docs/php/symfony/storyblok/webhook.mdx diff --git a/blog/2025-02-18-storyblok-webhooks.mdx b/blog/2025-02-18-storyblok-webhooks.mdx new file mode 100644 index 0000000..e1e0f38 --- /dev/null +++ b/blog/2025-02-18-storyblok-webhooks.mdx @@ -0,0 +1,11 @@ +--- +title: Storyblok Bundle Webhooks +authors: [jannik] +tags: [storyblok, symfony] +--- + +The installation guide for the [Storyblok Bundle] was updated. The new bundle version also includes the [new webhook integration]. + + +[Storyblok Bundle]: /docs/php/symfony/storyblok +[new webhook integration]: /docs/php/symfony/storyblok/webhook diff --git a/docs/php/symfony/storyblok/index.mdx b/docs/php/symfony/storyblok/index.mdx index fdeda61..78588f0 100644 --- a/docs/php/symfony/storyblok/index.mdx +++ b/docs/php/symfony/storyblok/index.mdx @@ -40,6 +40,9 @@ If you are using Symfony Flex you are all set. # your content token – with `preview` scope STORYBLOK_CONTENT_TOKEN= + + # the secret to validate webhooks + STORYBLOK_WEBHOOK_SECRET= ``` Then add the base config: @@ -49,5 +52,15 @@ If you are using Symfony Flex you are all set. space_id: "%env(int:STORYBLOK_SPACE_ID)%" management_token: "%env(STORYBLOK_MANAGEMENT_TOKEN)%" content_token: "%env(STORYBLOK_CONTENT_TOKEN)%" + webhook: + secret: "%env(STORYBLOK_WEBHOOK_SECRET)%" + ``` + + and load the routing: + + ```yaml title="config/routes/storyblok.yaml" + storyblok: + prefix: /storyblok/ + resource: '@TorrStoryblokBundle/config/routes.yaml' ``` diff --git a/docs/php/symfony/storyblok/webhook.mdx b/docs/php/symfony/storyblok/webhook.mdx new file mode 100644 index 0000000..9fe73ae --- /dev/null +++ b/docs/php/symfony/storyblok/webhook.mdx @@ -0,0 +1,129 @@ +# Webhooks + +The Storyblok bundle automatically integrates in to all webhooks that are sent from Storyblok. It parses the requests, validates it and passes properly typed events with payloads to your code, to integrate into your app. + +## Installation + +After setting up the bundle routes[^1], you need to configure the webhook URL in Storyblok: + +```txt +https://.../storyblok/webhook +``` + + +## Webhook Secrets + +You should always use webhook secrets to secure your webhook endpoints. The webhooks are a public endpoint, so anyone can send arbitrary requests to it. + +### For Paid Plans + +On paid plans, you can use the native **Webhooks Secret** feature. Configure the webhook secret in Storyblok and in your bundle: + +```yaml title="config/packages/storyblok.yaml" +storyblok: + webhook: + secret: "%env(STORYBLOK_WEBHOOK_SECRET)%" +``` + +### For Unpaid Plans + +Free plans (that are typically used during development) don't support proper webhook secrets, but this you can add the webhook secret to the URL. + +For that enable this feature: + +```yaml title="config/packages/storyblok.yaml" +storyblok: + webhook: + secret: "my-secret" + allow_url_secret: true +``` + +and append the secret to your webhook endpoint URL in the config: + +```txt +https://.../storyblok/webhook/my-secret +``` + +:::danger +Don't forget to rotate the secret when switching from an unpaid to a paid plan. You should always use proper webhook secrets if available. +::: + + +## Usage of Webhook Events + +For every webhook request a `StoryblokWebhookEvent` is dispatched. + +It provides the webhook payload and gives you the opportunity to pass arbitrary data to the webhook endpoint response. + +### Webhook Payloads + +The webhook payload defines the type of webhook that was dispatched. Right now the following webhook payloads are implemented: + +| Webhook Type | Payload | +|-----------------|---------------------------------| +| Story | `StoryWebhookPayload` | +| Datasource | `DatasourceEntryWebhookPayload` | +| Asset | `AssetWebhookPayload` | +| User management | `UserWebhookPayload` | +| Discussion | *(not yet implemented)* | +| Workflow | `WorkflowStageWebhookPayload` | +| Pipeline | `PipelineWebhookPayload` | +| Release | `ReleaseWebhookPayload` | + + +A typical implementation registers to the event and matches the payload type: + +```php +use Torr\Storyblok\Event\StoryblokWebhookEvent; + +public function onStoryblokWebhook (StoryblokWebhookEvent $event) : void +{ + switch (true) + { + case $event->payload instanceof StoryWebhookPayload: + // ... + break; + + case $event->payload instanceof AssetWebhookPayload: + // ... + break; + } +} +``` + +:::caution +The webhook event is dispatched synchronously in the webhook event handler. Make sure to always return a fast response, like just dispatching a message to the message bus. +::: + + +## Endpoint Response + +You can pass arbitrary response data to the `StoryblokWebhookEvent` to include in the webhook endpoint response: + +```php +use Torr\Storyblok\Event\StoryblokWebhookEvent; + +public function onStoryblokWebhook (StoryblokWebhookEvent $event) : void +{ + $event->addResponseData("some-data", "test"); +} +``` + +Will include + +```json +{ + "some-data": "test" +} +``` + +in the response. + +:::tip +Make sure to include useful information in the response, as you can then debug your webhooks (and their responses) in the Storyblok UI. +::: + + + + +[^1]: Follow the [installation guide](./#installation). You can see the details about setting up the routing if you open the "manual installation" section.