Storyblok Webhooks API

openapi: 3.2.0
info:
  title: Storyblok Management Webhooks API
  description: The Storyblok Management API is a REST API that allows developers to programmatically create, read, update, and delete content and configuration within a Storyblok space. It supports managing stories, components, assets, datasources, collaborators, webhooks, and space settings. The API uses OAuth or personal access tokens for authentication and is suitable for building editorial tooling, content migration scripts, CI/CD pipelines, and automated publishing workflows. All write operations are scoped to individual spaces and respect role-based access control.
  version: '1'
  contact:
    name: Storyblok Support
    url: https://www.storyblok.com/contact
  termsOfService: https://www.storyblok.com/legal/terms-of-service
servers:
- url: https://mapi.storyblok.com/v1
  description: Management API Production Server
security:
- personalAccessToken: []
- oauthToken: []
tags:
- name: Webhooks
  description: Webhooks allow external services to be notified when events occur in a Storyblok space, such as story publication or asset upload. The Management API provides full CRUD operations for webhook configuration.
paths:
  /spaces/{space_id}/webhook_endpoints:
    get:
      operationId: listWebhooks
      summary: List webhook endpoints
      description: Returns all webhook endpoints configured for the space, including their target URLs, event subscriptions, and optional secret configuration.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      responses:
        '200':
          description: A list of webhook endpoints was returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_endpoints:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhook
      summary: Create a webhook endpoint
      description: Registers a new webhook endpoint to receive event notifications from the space. Specify the target URL, the events to subscribe to, and an optional secret for signature validation.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook_endpoint
              properties:
                webhook_endpoint:
                  $ref: '#/components/schemas/WebhookEndpointInput'
      responses:
        '201':
          description: The webhook endpoint was created successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /spaces/{space_id}/webhook_endpoints/{webhook_id}:
    get:
      operationId: getWebhook
      summary: Retrieve a single webhook endpoint
      description: Returns the configuration of a single webhook endpoint by its numeric ID.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      - $ref: '#/components/parameters/WebhookId'
      responses:
        '200':
          description: The webhook endpoint was returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateWebhook
      summary: Update a webhook endpoint
      description: Updates an existing webhook endpoint's URL, subscribed events, or secret key.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      - $ref: '#/components/parameters/WebhookId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook_endpoint
              properties:
                webhook_endpoint:
                  $ref: '#/components/schemas/WebhookEndpointInput'
      responses:
        '200':
          description: The webhook endpoint was updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhook_endpoint:
                    $ref: '#/components/schemas/WebhookEndpoint'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteWebhook
      summary: Delete a webhook endpoint
      description: Permanently removes a webhook endpoint from the space. No further event notifications will be sent to the associated URL.
      tags:
      - Webhooks
      parameters:
      - $ref: '#/components/parameters/SpaceId'
      - $ref: '#/components/parameters/WebhookId'
      responses:
        '200':
          description: The webhook endpoint was deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    SpaceId:
      name: space_id
      in: path
      description: Numeric ID of the Storyblok space.
      required: true
      schema:
        type: integer
      example: 12345
    WebhookId:
      name: webhook_id
      in: path
      description: Numeric ID of the webhook endpoint.
      required: true
      schema:
        type: integer
      example: 33333
  responses:
    Unauthorized:
      description: Authentication failed. Verify the Authorization header contains a valid personal access token or OAuth token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request body contained validation errors. Check the error message for details on which fields failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    WebhookEndpoint:
      type: object
      description: A webhook endpoint that receives event notifications from the space when configured actions occur.
      properties:
        id:
          type: integer
          description: Unique numeric identifier of the webhook endpoint.
        url:
          type: string
          format: uri
          description: Target URL that receives the POST request when an event fires.
        name:
          type: string
          description: Optional display name for the webhook endpoint.
        actions:
          type: array
          description: List of event action strings this webhook is subscribed to, such as story.published or asset.created.
          items:
            type: string
        description:
          type: string
          nullable: true
          description: Optional description of the webhook's purpose.
        secret:
          type: string
          nullable: true
          description: Webhook secret key used to generate the webhook-signature HMAC-SHA1 header for payload verification. Only visible on creation.
        activated:
          type: boolean
          description: True if the webhook endpoint is active and will receive events.
        created_at:
          type: string
          format: date-time
          description: Creation timestamp.
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp.
    Error:
      type: object
      description: Error response returned when an API request fails.
      properties:
        error:
          type: string
          description: Human-readable message describing the error.
    WebhookEndpointInput:
      type: object
      description: Input for creating or updating a webhook endpoint.
      required:
      - url
      - actions
      properties:
        url:
          type: string
          format: uri
          description: Target URL that will receive POST requests on events.
        name:
          type: string
          description: Optional display name for the webhook endpoint.
        actions:
          type: array
          description: Event action strings to subscribe to. Valid actions include story.published, story.unpublished, story.deleted, story.moved, asset.created, asset.deleted, datasource.entries_updated.
          items:
            type: string
        description:
          type: string
          description: Optional description of the webhook's purpose.
        secret:
          type: string
          description: Optional secret key used to sign the webhook-signature header for payload integrity verification.
        activated:
          type: boolean
          description: Set to false to disable the webhook without deleting it.
  securitySchemes:
    personalAccessToken:
      type: http
      scheme: bearer
      description: Personal access token generated in the Storyblok account settings. Provides access to all spaces the account has permissions for.
    oauthToken:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token for third-party application integrations. Scoped to specific spaces and permissions granted during authorization.
externalDocs:
  description: Storyblok Management API Documentation
  url: https://www.storyblok.com/docs/api/management