Ellipse Gradient for Header

Storyblok Integration Guide

Integrate Storyblok content with enterprise applications through REST and GraphQL APIs, asset management endpoints, and selected webhook notifications.

Storyblok integration options at a glance

Storyblok provides REST APIs for content delivery and management, a GraphQL Content Delivery API for tailored queries, asset upload and management operations, and configurable webhooks for selected content and space events. Content Delivery API requests use space access tokens, while Management API integrations can use personal access tokens or OAuth 2.0. Martini can consume these APIs, expose a REST endpoint for Storyblok webhook calls, and orchestrate scheduled reconciliation when notifications are incomplete. Workflows can map nested Stories and Components, handle Assets separately, apply publication-state rules, and synchronize normalized content with downstream applications.

Integration pointSupported by Storyblok?Common use casesHow Martini supports it
REST APIsYesStoryblok’s Content Delivery API retrieves draft or published Stories and related content. The Management API supports administrative and content-management operations.Martini can consume both REST API surfaces from workflows, map responses, apply business rules, and write results to downstream systems.
GraphQL APIsYesThe GraphQL Content Delivery API supports tailored field selection, nested content retrieval, and consolidated queries across content structures.Martini can consume Storyblok GraphQL requests, transform the selected response shape, and route it to channel or enterprise application workflows.
WebhooksLimitedStoryblok provides configurable notifications for selected content and space events; coverage is not universal for every operation.Martini can expose a REST API to receive notifications, validate the request, enforce idempotency, and start an asynchronous workflow.
File and asset APIsYesStoryblok Management API operations support asset upload and metadata management for images and other files referenced by Stories.Martini can process asset uploads separately, handle upload responses, preserve identifiers and URLs, and associate assets with Story updates.
AuthenticationYesContent Delivery and GraphQL requests use space access tokens. Management API access supports personal access tokens and OAuth 2.0 with permission-scoped credentials.Martini can store tokens and credentials in secrets or environment configuration and apply them to API and webhook workflows.
Bulk or asynchronous APIsNot confirmedA generally applicable Storyblok bulk or asynchronous processing API was not confirmed.Martini can use scheduled workflows, pagination, filtering, checkpoints, controlled concurrency, and reconciliation instead of assuming bulk behavior.
Database accessNoStoryblok is a hosted CMS and direct customer database access was not confirmed.Martini should integrate through Storyblok APIs and webhooks rather than attempting direct database connectivity.

How Storyblok exposes data and business events

Storyblok REST APIs

Storyblok provides a Content Delivery API for retrieving draft or published Stories and a Management API for administrative and content-management operations. These APIs are the primary integration surface for reading content, managing workspace resources, and automating controlled synchronization.

Martini implementation pattern

Martini implementation pattern: a workflow authenticates with the appropriate space access token, personal access token, or OAuth credential, calls the relevant Storyblok endpoint, normalizes the response, applies business rules, and sends the result to one or more target systems.

Implementation sequence

Authenticate with the appropriate Storyblok credential
Retrieve Stories, Components, Assets, or other required resources
Apply pagination, filtering, and publication-state rules
Map the response to a canonical or target model
Write the result to downstream systems
Persist checkpoints and retry eligible failures

Storyblok GraphQL API

Storyblok’s GraphQL Content Delivery API is useful when an integration needs a tailored selection of fields, nested content, or related content in a single query. Access is associated with a Storyblok space and uses the relevant space access token.

Martini implementation pattern

Martini implementation pattern: a workflow sends a controlled GraphQL query, validates the response, transforms nested Stories and Components into a channel-specific payload, and routes the result to downstream APIs or publishing processes.

Implementation sequence

Configure the Storyblok GraphQL endpoint and space token
Send a query for the required content shape
Validate the GraphQL response and surface query errors
Transform nested content into the target model
Publish or store the transformed payload
Log failures and retry transient requests

Storyblok Webhooks

Storyblok supports configurable webhook notifications for selected content and space events. Event coverage depends on the webhook implementation and configuration, so notifications should be treated as triggers rather than complete synchronization payloads.

Martini implementation pattern

Martini implementation pattern: expose a Martini REST API, validate the configured webhook authentication, identify the affected Story or Space, enforce idempotency, and retrieve the current resource from Storyblok before processing downstream updates.

Implementation sequence

Receive the Storyblok webhook notification
Validate the request authentication and event payload
Create an idempotency key from the event and affected object
Retrieve the current Story or Space resource
Map and process the complete current representation
Return promptly and monitor the asynchronous workflow

Storyblok Asset APIs

Storyblok’s Management API includes asset upload and metadata-management operations. Asset processing may require multipart requests and separate response handling before the resulting URL or identifier is associated with a Story.

Martini implementation pattern

Martini implementation pattern: a workflow validates the source file, uploads or manages the Asset, captures the returned identifier or URL, and then updates the related Story or downstream content model with traceable asset information.

Implementation sequence

Validate the source file, MIME type, and size
Upload or manage the Storyblok Asset
Capture the returned asset identifier and URL
Associate the Asset with the relevant Story or Component
Record the source-to-Storyblok relationship
Retry transient upload failures without duplicating successful Assets

Common Storyblok integration patterns

Pattern 1: Publish Storyblok content to a search index

When to use this pattern

Use this pattern when selected Storyblok publishing events should refresh search quickly while scheduled reconciliation protects against missed or duplicated notifications.

Integration direction
Storyblok
Martini
Algolia
Example Mapping
Storyblok FieldCanonical FieldTarget Field
Story IDcontent.idobjectID
Story namecontent.titletitle
Story slugcontent.slugurl
Nested component textcontent.searchableText_searchableAttributes
Martini implementation pattern

Storyblok sends a selected webhook event to a Martini REST API. Martini validates the event, retrieves the complete Story through the Content Delivery API, flattens nested Components, applies publication and locale rules, and performs an idempotent index update. Failed requests are logged and retried, while scheduled reconciliation identifies missed changes.

Martini capabilities used
  • APIs
  • workflows
  • webhook handling
  • data mapping
  • business rules
  • error handling
  • scheduled synchronization

Pattern 2: Synchronize Storyblok content with a commerce platform

When to use this pattern

Use this pattern when Storyblok manages editorial content and a commerce platform remains the system of record for products, categories, pricing, inventory, and orders.

Integration direction
Storyblok
Martini
commercetools
Example Mapping
Storyblok FieldCanonical FieldTarget Field
Story IDcontent.idexternalContentId
Component typecontent.componentTypecontentType
Asset URLmedia.urlimageUrl
Publication statecontent.publicationStatestatus
Martini implementation pattern

A scheduled or webhook-triggered Martini workflow retrieves Stories, Assets, and Datasources, joins content to commerce identifiers, applies localization and publication rules, and sends idempotent updates. Rate limits and transient failures are handled with controlled concurrency and retry backoff.

Martini capabilities used
  • scheduled workflows
  • API consumption
  • data mapping
  • transformations
  • business rules
  • idempotency
  • retry handling

Pattern 3: Migrate legacy content into Storyblok

When to use this pattern

Use this pattern for a controlled migration from another CMS, database, or file source into Storyblok Stories and Components.

Integration direction
Contentful
Martini
Storyblok
Example Mapping
Storyblok FieldCanonical FieldTarget Field
Source entry IDsourceContentIdmigrationSourceId
Source content typesourceComponentTypecomponent
Source media URLsourceAssetasset
Source titletitlename
Martini implementation pattern

Martini reads source content, maps source fields into Storyblok Components and Stories, uploads Assets independently, and uses the Management API for creates or updates. A persistent source-to-Storyblok identifier map makes reruns safe, while validation and failed-object queues support reconciliation.

Martini capabilities used
  • workflows
  • API consumption
  • file handling
  • data mapping
  • validation
  • business rules
  • error handling

Pattern 4: Deliver Storyblok content to multiple channels

When to use this pattern

Use this pattern when Stories must be transformed into different payloads for websites, mobile applications, email, customer portals, or other enterprise channels.

Integration direction
Storyblok
Martini
Multiple enterprise channels
Example Mapping
Storyblok FieldCanonical FieldTarget Field
Story fieldscontent.fieldschannel.content
Nested Componentscontent.blockschannel.blocks
Datasource keycontent.referenceKeychannel.reference
Asset URLmedia.urlchannel.mediaUrl
Martini implementation pattern

Martini queries Storyblok through REST or GraphQL, transforms nested content into channel-specific structures, and routes each output to the required application or API. Webhooks can trigger targeted refreshes, while scheduled workflows provide reconciliation and recover from unavailable downstream systems.

Martini capabilities used
  • REST API consumption
  • GraphQL API consumption
  • workflow orchestration
  • mapping
  • transformation
  • conditional routing
  • scheduling
  • monitoring

Applications commonly integrated with Storyblok

Storyblok can be integrated with commerce, search, marketing, and other content platforms through its documented APIs and selected webhooks. These are typical enterprise architecture scenarios rather than claims of native Storyblok integrations.

Application Scenario Direction Martini Pattern
Shopify Combine Storyblok editorial content with Shopify products, collections, and commerce experiences. Storyblok → Martini → Shopify Martini retrieves Stories, Assets, and relevant Datasources, maps editorial fields to storefront-facing content, and applies publication and localization rules before sending the result to Shopify-facing services or synchronization workflows.
commercetools Coordinate editorial content with commercetools product and category data in composable commerce implementations. Storyblok → Martini → commercetools A scheduled or webhook-triggered workflow retrieves current Storyblok content, joins it with commercetools identifiers, transforms Components into channel payloads, and retries transient downstream failures.
Salesforce Commerce Cloud Support coordinated CMS content, campaign information, and storefront experiences. Storyblok → Martini → Salesforce Commerce Cloud Martini consumes Storyblok REST or GraphQL content, applies storefront and publication-state rules, and delivers normalized content to Salesforce Commerce Cloud integration endpoints or an intermediate publishing layer.
Algolia Index Storyblok Stories and searchable fields for website and application search. Storyblok → Martini → Algolia Storyblok webhooks can start a Martini workflow for selected changes; the workflow retrieves the complete Story, flattens nested Components, maps searchable fields, and upserts an idempotent Algolia document.
Contentful Migrate or consolidate content between headless CMS platforms. Contentful → Martini → Storyblok Martini reads Contentful content, maps source entries into Storyblok Components and Stories, uploads Assets separately, stores source-to-Storyblok identifiers, and supports safe reruns.
Sanity Support a multi-CMS transition or editorial content migration program. Sanity → Martini → Storyblok A Martini workflow retrieves Sanity content, transforms schemas into Storyblok component structures, uploads media through the Management API, and records migration status for retry and reconciliation.
HubSpot Coordinate marketing content, landing-page-related data, forms, or campaign metadata with a Storyblok-managed digital experience. HubSpot → Martini → Storyblok Martini receives or retrieves selected HubSpot data, validates the business scope, maps approved fields to Storyblok Stories or Datasources, and uses Management API credentials stored in environment configuration.
Adobe Experience Manager Support phased migration, coexistence, or controlled content exchange between enterprise CMS platforms. Adobe Experience Manager → Martini → Storyblok Martini extracts source content, maps it into Storyblok Components and Stories, handles Assets independently, and maintains identifiers and checkpoints to support migration reconciliation.

How to build a Storyblok integration in Martini

Objective

Configure the Storyblok API endpoints and environment-specific credentials without embedding secrets in workflows or mappings.

Instructions in Martini

  • Choose Content Delivery, GraphQL, or Management API access for the use case.
  • Store space tokens, personal access tokens, or OAuth credentials in Martini secrets or environment configuration.
  • Separate draft, published, development, and production credentials where required.
  • Apply least-privilege permissions to Management API credentials.

Objective

Select an event-driven or scheduled entry point based on the availability and completeness of Storyblok webhook coverage.

Instructions in Martini

  • Expose a Martini REST API for selected Storyblok webhook events.
  • Use a scheduler for periodic synchronization and reconciliation.
  • Treat webhook notifications as triggers and retrieve the current resource before processing.
  • Define an idempotency key using the Story identifier and event or version context.

Objective

Retrieve the complete Storyblok representation needed by the downstream process rather than relying only on notification payloads.

Instructions in Martini

  • Call the Content Delivery API for content retrieval workflows.
  • Use GraphQL when a tailored field selection or nested query is useful.
  • Use the Management API for administrative, content-management, and asset operations.
  • Apply documented pagination, filtering, and publication-state parameters.

Objective

Coordinate retrieval, validation, transformation, target writes, and state management in a maintainable Martini workflow.

Instructions in Martini

  • Separate webhook receipt from longer-running downstream processing where appropriate.
  • Route Stories, Assets, Datasources, and release context according to the integration design.
  • Use conditional branches for draft, published, locale, component, and target-system rules.
  • Persist checkpoints and failed-object details for replay.

Objective

Convert nested Storyblok content structures into canonical or target-specific application models.

Instructions in Martini

  • Map Stories and nested Components rather than only top-level fields.
  • Handle optional fields, unknown properties, and component-type changes safely.
  • Flatten or reshape content for search, commerce, mobile, email, or portal consumers.
  • Preserve Storyblok identifiers, publication context, and Asset URLs for traceability.

Objective

Prevent invalid or inappropriate content from reaching production systems and ensure environment-specific behavior is explicit.

Instructions in Martini

  • Prevent draft content from being sent to production targets.
  • Apply localization, publication, release, and content-type rules.
  • Validate required fields and target-system constraints before writes.
  • Decide whether an Asset must be uploaded, reused, or associated with an existing Story.

Common Storyblok data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
StoriesPrimary content entries delivered to websites and applications, including nested Components and publication state.Websites, commerce platforms, search indexes, mobile applications, and customer portalsMartini retrieves Stories through REST or GraphQL, maps nested content into canonical models, applies draft or published rules, and uses identifiers for idempotent updates.
ComponentsReusable content schemas and nested blocks that structure Story content.Websites, storefronts, mobile channels, search, and downstream content repositoriesMartini treats component schemas as external contracts, supports optional and nested fields, and transforms component types into target-specific structures.
AssetsImages, files, and media resources referenced by Stories.Websites, commerce platforms, DAM-related processes, and publishing pipelinesMartini handles uploads and metadata separately from Story synchronization, preserving asset identifiers and URLs and preventing duplicate uploads where possible.
SpacesTenant-like workspaces containing Stories, Components, Assets, configurations, and related resources.Provisioning tools, governance systems, reporting stores, and enterprise administration workflowsMartini uses Management API credentials and permissions to synchronize or automate selected space-level operations without direct database access.
DatasourcesReusable key-value content collections referenced by Components or applications.Websites, applications, localization services, commerce experiences, and channel payloadsMartini retrieves and maps Datasources with the relevant Stories, applies environment and localization rules, and preserves keys for stable downstream references.
ReleasesGrouped publishing or content-release configurations used to organize content changes.Publishing workflows, deployment controls, editorial governance, and content audit storesMartini can include release and publication context in synchronization logic where exposed by the applicable Management API operations.

Authentication and security considerations

Credential types

Storyblok Content Delivery and GraphQL requests use space access tokens. Management API integrations can use personal access tokens or OAuth 2.0, with access governed by user, organization, and space permissions.

Secret handling

Store Storyblok tokens, OAuth credentials, and webhook verification values in Martini secrets or environment-specific configuration rather than workflow payloads, mappings, or source code.

Webhook protection

Validate the authentication, secret, custom header, signature, or other mechanism configured for the Storyblok webhook. Keep webhook processing scoped to the expected space and event types.

Environment separation

Use separate credentials and explicit API modes for draft, preview, and published content so preview data is not accidentally synchronized to production systems.

Operational considerations for Storyblok integrations

Pagination and checkpoints

Use the pagination and filtering parameters documented for each Storyblok API. Do not assume Content Delivery API and Management API pagination behave identically. Store checkpoints based on supported modification or publication fields where available.

Rate limits and retries

Confirm applicable limits for the Storyblok plan and endpoint. Use controlled concurrency, retry backoff, and classification of transient versus permanent failures.

Webhooks and idempotency

Webhook notifications may be retried or delivered more than once. Use the Story identifier, event type, version or update timestamp, and a stored processing key to prevent duplicate downstream updates.

Nested content and schemas

Stories can contain nested Components and blocks. Mappings should tolerate optional fields and unknown properties while monitoring for new component types and schema changes.

Asset processing

Handle asset uploads separately from Story updates. Consider file size, MIME type, duplicate uploads, returned identifiers, and association of the resulting URL with the correct Story.

Testing and reconciliation

Test draft and published paths, webhook failures, pagination, rate limiting, schema changes, and partial target outages. Use scheduled reconciliation to detect changes missed while a receiver or downstream system was unavailable.

Why use Martini instead of scripts or point-to-point integrations?

Reusable orchestration

Martini coordinates Storyblok API calls, webhook receipt, asset processing, downstream writes, validation, and reconciliation in maintainable workflows rather than embedding all behavior in a single script.

Flexible integration models

Teams can combine REST, GraphQL, webhook, scheduled, file, and database-facing integration steps where required. Martini can also expose controlled APIs for normalized content or integration operations.

Consistent transformation

Mappings and business rules provide a repeatable way to convert nested Storyblok Stories and Components into commerce, search, mobile, portal, or migration models.

Operational control

Centralized error handling, retries, checkpoints, logging, environment configuration, and secret management make integrations easier to monitor and evolve than isolated point-to-point scripts.

Frequently asked questions

How can Storyblok be integrated with enterprise systems?

Storyblok can be integrated through its Content Delivery and Management REST APIs, GraphQL Content Delivery API, asset-management endpoints, and configurable webhooks for selected content and space events. Enterprise workflows can retrieve or manage Stories, Components, Assets, Datasources, and other resources, then synchronize them with downstream applications.

Can Martini integrate with Storyblok?

Yes. Martini can consume Storyblok REST and GraphQL APIs, expose a REST API for selected Storyblok webhook notifications, store Storyblok credentials securely, and orchestrate content, asset, migration, and reconciliation workflows.

Do I need a connector to integrate Storyblok with Martini?

No. A dedicated Storyblok connector is not required. Martini can use Storyblok’s documented REST APIs, GraphQL API, asset endpoints, authentication methods, and selected webhook notifications through workflows and APIs.

Is there any extra Lonti cost to integrate Storyblok with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate Storyblok. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Storyblok, cloud infrastructure, or other third-party systems depending on subscriptions, usage, and deployment model.

Which Storyblok APIs should an integration use?

Use the Content Delivery API for conventional retrieval of draft or published content, the GraphQL Content Delivery API for tailored or nested queries, and the Management API for administrative, content-management, asset, and provisioning operations. The appropriate choice depends on the data shape and level of control required.

Can Martini receive Storyblok webhook events?

Yes. Storyblok supports configurable webhooks for selected events, and Martini can expose a REST endpoint to receive them. Coverage is event-specific, so integrations should validate notifications, retrieve the current Story or Space resource, apply idempotency, and use scheduled reconciliation for missed events.

How does Martini synchronize and transform Storyblok content?

Martini can use webhook-triggered or scheduled workflows to retrieve Stories, Components, Assets, Datasources, and related context. It maps nested content into canonical or target-specific models, applies publication and localization rules, and writes idempotent updates to downstream applications.

How are Storyblok errors, retries, and duplicate events handled?

A Martini workflow can distinguish authentication, permission, validation, rate-limit, and transient server failures. It can apply controlled retries and backoff, persist failed Story identifiers and response details, use stable idempotency keys, and run scheduled reconciliation to recover from missed notifications. Martini can also expose an API façade for controlled access to normalized Storyblok content or integration operations.

Related Martini documentation

API access

Workflows

Security

Operations

Integrate Storyblok with Martini

Use Martini to connect Storyblok content, assets, and publishing events with enterprise applications through secure APIs and reliable workflows.

EXPLORE MARTINI
BOOK A DEMO