Storyblok Webhooks

asyncapi: 2.6.0
info:
  title: Storyblok Webhooks
  description: >-
    The Storyblok Webhook system delivers real-time event notifications to
    registered HTTP endpoints when content events occur in a Storyblok space.
    Events are triggered by actions such as story publication, unpublication,
    deletion, asset upload, and datasource updates. Webhook payloads are
    delivered as HTTP POST requests with a JSON body and an optional
    HMAC-SHA1 signature header for payload integrity verification.
    Webhooks are configured per space and managed via the Management API or
    the Storyblok dashboard.
  version: '1'
  contact:
    name: Storyblok Support
    url: https://www.storyblok.com/contact
externalDocs:
  description: Storyblok Webhooks Documentation
  url: https://www.storyblok.com/docs/concepts/webhooks
servers:
  customerEndpoint:
    url: '{webhookUrl}'
    protocol: https
    description: >-
      The customer-defined HTTPS endpoint registered to receive webhook event
      notifications from Storyblok. The URL is configured when creating a
      webhook endpoint via the Management API or dashboard.
    variables:
      webhookUrl:
        description: >-
          The fully-qualified HTTPS URL of the endpoint that will receive
          webhook POST requests from Storyblok.
    security:
      - webhookSignature: []
channels:
  /webhook:
    description: >-
      The webhook delivery channel. Storyblok POSTs event payloads to the
      registered endpoint URL when subscribed actions occur in the space.
      The endpoint must respond with a 2xx HTTP status code within 120 seconds
      to be considered a successful delivery. For long-running tasks, respond
      immediately with 202 Accepted and process asynchronously.
    publish:
      operationId: receiveStoryblokEvent
      summary: Receive a Storyblok space event notification
      description: >-
        Called by Storyblok when a subscribed event fires in the space. The
        payload identifies the action type, the affected resource IDs, and the
        space context. Verify the webhook-signature header before processing
        the payload to ensure the request originated from Storyblok.
      message:
        oneOf:
          - $ref: '#/components/messages/StoryPublished'
          - $ref: '#/components/messages/StoryUnpublished'
          - $ref: '#/components/messages/StoryDeleted'
          - $ref: '#/components/messages/StoryMoved'
          - $ref: '#/components/messages/AssetCreated'
          - $ref: '#/components/messages/AssetDeleted'
          - $ref: '#/components/messages/DatasourceEntriesUpdated'
components:
  securitySchemes:
    webhookSignature:
      type: httpApiKey
      in: header
      name: webhook-signature
      description: >-
        HMAC-SHA1 signature of the raw request body, generated using the
        webhook secret configured on the endpoint. Recipients should compute
        the HMAC-SHA1 of the raw body bytes using the shared secret and
        compare it to this header value to verify authenticity.

  messages:
    StoryPublished:
      name: StoryPublished
      title: Story Published
      summary: A story was published in the space.
      description: >-
        Delivered when a story transitions to published state, either via
        the editor, the Management API, or a scheduled publication. This
        event is useful for triggering cache invalidation, static site
        rebuilds, or search index updates.
      contentType: application/json
      headers:
        type: object
        properties:
          webhook-signature:
            type: string
            description: >-
              HMAC-SHA1 signature of the raw request body for integrity
              verification.
          content-type:
            type: string
            description: Always application/json.
      payload:
        $ref: '#/components/schemas/StoryEventPayload'
      examples:
        - name: StoryPublishedExample
          payload:
            action: published
            story_id: 123456
            space_id: 12345
            text: Story "My Blog Post" (123456) published
            full_slug: blog/my-blog-post

    StoryUnpublished:
      name: StoryUnpublished
      title: Story Unpublished
      summary: A story was unpublished in the space.
      description: >-
        Delivered when a published story is unpublished, removing it from
        public access via the Content Delivery API. Useful for cache
        invalidation and removal from search indexes.
      contentType: application/json
      headers:
        type: object
        properties:
          webhook-signature:
            type: string
            description: HMAC-SHA1 signature for integrity verification.
      payload:
        $ref: '#/components/schemas/StoryEventPayload'
      examples:
        - name: StoryUnpublishedExample
          payload:
            action: unpublished
            story_id: 123456
            space_id: 12345
            text: Story "My Blog Post" (123456) unpublished

    StoryDeleted:
      name: StoryDeleted
      title: Story Deleted
      summary: A story was permanently deleted from the space.
      description: >-
        Delivered when a story is deleted from the space. After deletion, the
        story is no longer accessible via either the Content Delivery or
        Management APIs. Useful for cleaning up derived data such as search
        index entries or generated files.
      contentType: application/json
      headers:
        type: object
        properties:
          webhook-signature:
            type: string
            description: HMAC-SHA1 signature for integrity verification.
      payload:
        $ref: '#/components/schemas/StoryEventPayload'
      examples:
        - name: StoryDeletedExample
          payload:
            action: deleted
            story_id: 123456
            space_id: 12345
            text: Story "My Blog Post" (123456) deleted

    StoryMoved:
      name: StoryMoved
      title: Story Moved
      summary: A story was moved to a different folder in the space.
      description: >-
        Delivered when a story's position in the folder hierarchy changes,
        resulting in a new full_slug. Useful for updating navigation caches,
        redirects, and sitemap data that depend on story URLs.
      contentType: application/json
      headers:
        type: object
        properties:
          webhook-signature:
            type: string
            description: HMAC-SHA1 signature for integrity verification.
      payload:
        $ref: '#/components/schemas/StoryEventPayload'
      examples:
        - name: StoryMovedExample
          payload:
            action: moved
            story_id: 123456
            space_id: 12345
            text: Story "My Blog Post" (123456) moved

    AssetCreated:
      name: AssetCreated
      title: Asset Created
      summary: A new asset was uploaded to the space.
      description: >-
        Delivered when a new file is successfully uploaded to the space's
        asset library. Includes the asset ID so the asset details can be
        retrieved via the Management API if needed.
      contentType: application/json
      headers:
        type: object
        properties:
          webhook-signature:
            type: string
            description: HMAC-SHA1 signature for integrity verification.
      payload:
        $ref: '#/components/schemas/AssetEventPayload'
      examples:
        - name: AssetCreatedExample
          payload:
            action: created
            asset_id: 78901
            space_id: 12345
            text: Asset "hero-image.jpg" (78901) created

    AssetDeleted:
      name: AssetDeleted
      title: Asset Deleted
      summary: An asset was deleted from the space.
      description: >-
        Delivered when an asset is removed from the space's asset library.
        Stories that reference the deleted asset will display broken media.
        Use this event to clean up any external references to the asset.
      contentType: application/json
      headers:
        type: object
        properties:
          webhook-signature:
            type: string
            description: HMAC-SHA1 signature for integrity verification.
      payload:
        $ref: '#/components/schemas/AssetEventPayload'
      examples:
        - name: AssetDeletedExample
          payload:
            action: deleted
            asset_id: 78901
            space_id: 12345
            text: Asset "hero-image.jpg" (78901) deleted

    DatasourceEntriesUpdated:
      name: DatasourceEntriesUpdated
      title: Datasource Entries Updated
      summary: Datasource entries were created, updated, or deleted.
      description: >-
        Delivered when entries in a datasource are modified via the Management
        API or editor. Useful for invalidating caches that depend on datasource
        values such as navigation options or translations.
      contentType: application/json
      headers:
        type: object
        properties:
          webhook-signature:
            type: string
            description: HMAC-SHA1 signature for integrity verification.
      payload:
        $ref: '#/components/schemas/DatasourceEventPayload'
      examples:
        - name: DatasourceUpdatedExample
          payload:
            action: entries_updated
            datasource_id: 456
            space_id: 12345
            text: Datasource "Colors" (456) entries updated

  schemas:
    StoryEventPayload:
      type: object
      description: >-
        Payload delivered by Storyblok for story-related webhook events.
        Identifies the affected story, the action performed, and the space
        context.
      required:
        - action
        - story_id
        - space_id
        - text
      properties:
        action:
          type: string
          description: >-
            The event action that triggered the webhook. One of published,
            unpublished, deleted, or moved.
          enum:
            - published
            - unpublished
            - deleted
            - moved
        story_id:
          type: integer
          description: Numeric ID of the story that triggered the event.
        space_id:
          type: integer
          description: Numeric ID of the space in which the event occurred.
        text:
          type: string
          description: >-
            Human-readable description of the event, including the story name,
            ID, and action.
        full_slug:
          type: string
          description: >-
            Full URL slug of the story at the time of the event. Present for
            published and moved events.

    AssetEventPayload:
      type: object
      description: >-
        Payload delivered by Storyblok for asset-related webhook events.
        Identifies the affected asset, the action performed, and the space
        context.
      required:
        - action
        - asset_id
        - space_id
        - text
      properties:
        action:
          type: string
          description: The event action. One of created or deleted.
          enum:
            - created
            - deleted
        asset_id:
          type: integer
          description: Numeric ID of the asset that triggered the event.
        space_id:
          type: integer
          description: Numeric ID of the space in which the event occurred.
        text:
          type: string
          description: >-
            Human-readable description of the event, including the asset
            filename, ID, and action.

    DatasourceEventPayload:
      type: object
      description: >-
        Payload delivered by Storyblok for datasource-related webhook events.
        Identifies the affected datasource and the space context.
      required:
        - action
        - datasource_id
        - space_id
        - text
      properties:
        action:
          type: string
          description: The event action. Currently entries_updated.
          enum:
            - entries_updated
        datasource_id:
          type: integer
          description: Numeric ID of the datasource that was updated.
        space_id:
          type: integer
          description: Numeric ID of the space in which the event occurred.
        text:
          type: string
          description: Human-readable description of the datasource update event.