.png)
Contentful Integration Guide
Integrate Contentful content with enterprise applications through REST and GraphQL APIs, selected-event webhooks, and incremental synchronization.
Contentful integration options at a glance
Contentful provides REST APIs for content delivery, preview, management, synchronization, and image operations, alongside a GraphQL Content API for selective content queries. Its selected-event webhooks can initiate downstream processing for entry, asset, and publishing activity, while the Sync API supports incremental synchronization of published content. Contentful also supports operation-specific bulk actions and asset processing through its management capabilities. Martini can consume these APIs, receive webhook requests, persist synchronization tokens, transform Contentful JSON, apply lifecycle and locale rules, and expose controlled REST APIs for applications that should not access Contentful directly. API tokens and OAuth credentials are secured through Martini configuration.
| Integration point | Supported by Contentful? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Content Delivery, Preview, Management, Sync, and Images APIs support published and preview retrieval, content administration, incremental synchronization, and image operations. | Martini can consume Contentful REST endpoints, map JSON responses, orchestrate dependent calls, and expose a controlled REST façade. |
| GraphQL APIs | Yes | The GraphQL Content API supports selective queries against published or preview content models and entries. Management mutations generally use the Content Management API. | Martini can consume GraphQL queries, supply secured variables, transform responses, and route query results to downstream applications. |
| Webhooks / outbound callbacks | Limited | Selected entry, asset, and publishing-related events can notify external HTTP endpoints. Webhooks are not a complete all-events synchronization stream. | Martini can expose an HTTP endpoint or webhook-consuming workflow, validate the request, retrieve the current object, and deduplicate deliveries. |
| Incremental synchronization | Yes | The Sync API retrieves published content changes using an initial synchronization token and subsequent tokens, including created, updated, and deleted Entries or Assets. | Martini can schedule synchronization, persist tokens in a durable store, process changes, and checkpoint only after successful completion. |
| Bulk / asynchronous actions | Limited | The Content Management API provides bulk actions for supported operations, with coverage and asynchronous behavior varying by operation. | Martini can invoke supported bulk actions and track response or completion semantics explicitly rather than assuming universal batch behavior. |
| File / asset APIs | Yes | Contentful Assets represent images, documents, and other uploaded media, including metadata and file-processing operations. | Martini can retrieve, transform, distribute, or manage Asset metadata and account for separate processing or publishing steps. |
| Authentication | Yes | Contentful supports Delivery and Preview API tokens, Management API personal access tokens, and OAuth 2.0 for delegated applications, subject to roles and permissions. | Martini can store credentials in secrets or secured environment configuration and apply the appropriate authentication to each API workflow. |
| Database access | No | Customer integrations should use Contentful APIs and webhooks; direct database access is not a documented integration mechanism. | Martini should integrate through Contentful APIs, webhook endpoints, and durable stores under the integration team's control. |
How Contentful exposes data and business events
Contentful REST APIs
Contentful's REST APIs cover delivery of published content, preview retrieval, content management, synchronization, and image operations. The appropriate API depends on lifecycle state and whether the workflow reads, manages, or incrementally synchronizes content.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates to the selected Contentful API, retrieves paginated JSON, follows related calls where required, maps Entries or Assets into a canonical model, and sends the result to a target system or returns it through a Martini API.
Implementation sequence
Contentful GraphQL API
Contentful's GraphQL Content API provides selective queries against published or preview content models. It is primarily a query interface; content-management mutations generally use the Content Management API.
Martini implementation pattern
Martini implementation pattern: an API or workflow supplies a controlled GraphQL query and variables, authenticates with the appropriate Delivery or Preview token, validates the response, and transforms the selected fields for the consuming application.
Implementation sequence
Contentful webhooks
Contentful supports selected-event webhook notifications for entry, asset, and publishing-related activity. These notifications can initiate downstream processing but do not replace the Sync API for comprehensive incremental synchronization.
Martini implementation pattern
Martini implementation pattern: a Martini endpoint receives the notification, validates the configured webhook security mechanism, retrieves the current Contentful object, and processes the authoritative state with duplicate, ordering, and retry controls.
Implementation sequence
Contentful Sync API
The Sync API supports incremental synchronization of published Contentful content using an initial synchronization token and subsequent tokens. It is suitable for reconciliation of Entries and Assets, including changes and deletions.
Martini implementation pattern
Martini implementation pattern: a scheduled workflow reads the last successful token from durable storage, requests the next change set, processes all changes, and persists the returned token only after downstream writes succeed.
Implementation sequence
Contentful Content Management API
The Content Management API manages supported Contentful resources such as Spaces, Environments, Content types, Entries, Assets, and Locales. Bulk actions are available for supported operations, and lifecycle steps may include draft, processing, version, and publish behavior.
Martini implementation pattern
Martini implementation pattern: a controlled Martini API validates an internal request, applies naming and authorization rules, invokes the relevant management operation, and reports completion only when the Contentful lifecycle response supports that conclusion.
Implementation sequence
Common Contentful integration patterns
Pattern 1: Index published content in Algolia
When to use this pattern
Use this pattern when published Entries and Assets must become searchable quickly while retaining a reliable reconciliation path. Selected Contentful webhook events provide the trigger, while the Sync API can repair missed or delayed notifications.
Integration direction
Example Mapping
| Contentful Field | Canonical Field | Target Field |
|---|---|---|
| sys.id | contentId | objectID |
| fields.title | title | title |
| fields.slug | slug | urlSlug |
| sys.updatedAt | updatedAt | contentUpdatedAt |
Martini implementation pattern
Martini receives a selected-event webhook, retrieves the current published object through the Delivery API, expands the required fields, and maps it to an Algolia document. The workflow rejects incomplete content, handles deletion events, uses content IDs for idempotency, and retries transient downstream failures. A scheduled Sync API workflow can reconcile the index.
Martini capabilities used
- workflows
- API consumption
- webhook receiving
- data mapping
- business rules
- error handling
- scheduled synchronization
Pattern 2: Synchronize Contentful changes to a data store
When to use this pattern
Use this pattern when a warehouse, cache, or application database needs a complete incremental view of published Contentful content rather than relying only on selected webhook events.
Integration direction
Example Mapping
| Contentful Field | Canonical Field | Target Field |
|---|---|---|
| sys.id | sourceId | contentful_id |
| sys.type | objectType | content_type |
| sys.updatedAt | sourceUpdatedAt | updated_at |
| fields | localizedContent | content_json |
Martini implementation pattern
A scheduled Martini workflow reads a durable Sync API token, requests changes, transforms Entries and Assets into database rows or JSON documents, and applies upserts or tombstones. It commits the next token only after all writes succeed, making a failed run replayable and protecting against duplicate processing.
Martini capabilities used
- scheduled workflows
- API consumption
- database connectivity
- JSON handling
- data mapping
- idempotency
- error handling
Pattern 3: Expose a controlled Contentful management façade
When to use this pattern
Use this pattern when internal applications need to create or update Contentful content without receiving direct Contentful credentials or implementing Contentful lifecycle rules themselves.
Integration direction
Example Mapping
| Contentful Field | Canonical Field | Target Field |
|---|---|---|
| request.contentType | contentModel | Contentful contentType |
| request.fields | contentFields | Entry fields |
| request.environment | targetEnvironment | Contentful Environment |
| request.publish | publishRequested | lifecycle action |
Martini implementation pattern
Martini exposes a secured REST API that validates the request, authorizes the caller, applies naming and environment rules, and calls the Content Management API. It distinguishes draft, version, processing, and publishing outcomes, records an audit result, and returns clear failure responses for validation or Contentful conflicts.
Martini capabilities used
- API exposure
- workflows
- authentication and authorization
- data mapping
- business rules
- validation
- error handling
Pattern 4: Distribute product content to commerce applications
When to use this pattern
Use this pattern when Contentful manages editorial descriptions, landing content, or media while a commerce platform remains authoritative for transactions, pricing, or order operations.
Integration direction
Example Mapping
| Contentful Field | Canonical Field | Target Field |
|---|---|---|
| sys.id | contentId | externalContentId |
| fields.productReference | productReference | productId |
| fields.title | productTitle | title |
| fields.image | primaryAsset | imageReference |
Martini implementation pattern
Martini retrieves product-related Entries and Assets through the Delivery API or Sync API, applies environment, locale, channel, and publishing rules, then maps the approved content to the commerce application's API. The workflow records source IDs, handles missing references, avoids publishing draft content, and retries rate-limited requests.
Martini capabilities used
- workflows
- REST API consumption
- data mapping
- locale handling
- business rules
- rate-limit handling
- retry processing
Applications commonly integrated with Contentful
Contentful is commonly placed in a composable content architecture alongside commerce, search, CRM, workflow, and media platforms. Martini can coordinate these integrations while keeping content lifecycle, transformation, authentication, and retry logic in reusable workflows.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize customer-facing, campaign, or product-related content with CRM processes and selected Salesforce metadata. | Contentful → Martini → Salesforce | Receive Contentful webhook notifications or run a scheduled Sync API workflow, retrieve authoritative Entries and Assets, map approved content into Salesforce fields, and apply idempotency and retry handling. |
| Shopify | Distribute editorial product content, landing pages, and media to a commerce storefront while Shopify remains the transaction system. | Contentful → Martini → Shopify | Use Contentful webhooks for selected publishing events or the Sync API for reconciliation, apply locale and channel rules, and send normalized content and asset references to Shopify APIs. |
| Adobe Commerce | Combine Contentful-managed editorial content with Adobe Commerce catalog and commerce operations. | Contentful → Martini → Adobe Commerce | Retrieve Contentful Entries and Assets, enrich them with commerce identifiers where required, validate publishing state, and distribute the resulting content through a Martini workflow. |
| NetSuite | Coordinate ERP product or operational data with content managed in Contentful and downstream commerce or customer-experience applications. | NetSuite → Martini → Contentful | Orchestrate source data retrieval, map product or operational attributes into Contentful content models, apply environment and approval rules, and call the Content Management API for supported updates. |
| Algolia | Index published Contentful Entries and Assets for site search, filtering, and discovery. | Contentful → Martini → Algolia | Use selected Contentful webhook events for near-real-time indexing and the Sync API for reconciliation, transform content into search documents, and handle deletes and duplicate deliveries. |
| Jira | Create or update content-related work items for editorial, localization, or approval processes. | Contentful → Martini → Jira | Trigger from selected content events or scheduled checks, map content identifiers and lifecycle state to Jira work items, and optionally return status metadata through a controlled workflow. |
| Cloudinary | Coordinate media metadata and asset workflows between Contentful and a specialized media platform. | Cloudinary → Martini → Contentful | Compare asset identifiers and metadata, apply authority and publishing rules, then update Contentful Assets or downstream media references through API-based workflows. |
| ServiceNow | Route content-publishing incidents, approvals, or operational requests into service-management workflows. | Contentful → Martini → ServiceNow | Create or update ServiceNow work items from selected Contentful events, include content and environment context, and handle acknowledgement and retry states in Martini. |
How to build a Contentful integration in Martini
Objective
Configure the Contentful space, environment, API endpoint, and authentication method appropriate to the workflow.
Instructions in Martini
- Use Delivery or Preview tokens for content retrieval and Management tokens or OAuth 2.0 for management operations.
- Store tokens, OAuth credentials, and webhook secrets in Martini secrets or secured environment configuration.
- Keep space and environment values separate for development, staging, and production.
Objective
Select an event-driven, scheduled, or API-led entry point based on completeness and latency requirements.
Instructions in Martini
- Use a Contentful webhook for selected entry, asset, or publishing events.
- Use a scheduled workflow with the Sync API for comprehensive incremental synchronization.
- Expose a Martini REST API when internal applications need a controlled Contentful façade.
Objective
Obtain the authoritative Contentful object and all required pages or related resources.
Instructions in Martini
- Retrieve the current Entry or Asset after a webhook notification.
- Follow Contentful pagination metadata for collection responses.
- Select the Delivery, Preview, or Management API according to content lifecycle state.
Objective
Coordinate Contentful calls, downstream requests, checkpointing, and lifecycle operations in a maintainable Martini workflow.
Instructions in Martini
- Separate webhook acknowledgement from longer downstream processing where appropriate.
- Persist Sync API tokens in a durable store and checkpoint only after successful processing.
- Track draft, processing, version, and publishing outcomes explicitly.
Objective
Transform Contentful JSON, localized fields, and Asset metadata into a canonical or target-specific model.
Instructions in Martini
- Map actual Contentful object and field names to target fields.
- Define locale fallback behavior and tolerate optional content-model fields.
- Validate required fields, references, publishing state, and schema assumptions before writing downstream.
Objective
Enforce business, environment, channel, authorization, and idempotency rules before side effects occur.
Instructions in Martini
- Reject draft or unpublished content when the target requires published data.
- Use Contentful IDs, versions, or event identifiers as idempotency keys where available.
- Apply target-specific locale, channel, deletion, and asset-readiness policies.
Common Contentful data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Spaces | Top-level containers for Contentful content and configuration. | Contentful administration services, configuration stores, and deployment processes | Martini uses space identifiers as secured, environment-specific configuration when calling Contentful APIs. |
| Environments | Isolated development, staging, or production content contexts. | Contentful, release workflows, commerce platforms, and applications | Martini selects the intended environment through configuration and applies environment-specific routing and publishing rules. |
| Content types | Schemas defining fields and validation rules for structured content. | Contentful management processes, validation services, and downstream content models | Martini validates and maps content-type-specific fields while tolerating optional fields and model evolution. |
| Entries | Structured content records based on Contentful content types. | Search platforms, commerce applications, CRMs, caches, and data stores | Martini retrieves Entries through REST or GraphQL, transforms localized fields, applies business rules, and synchronizes creates, updates, and deletes. |
| Assets | Images, documents, and other uploaded media with metadata and processing state. | Commerce storefronts, search platforms, media services, and content delivery layers | Martini maps asset metadata and URLs, checks processing or publishing state, and handles asset deletion explicitly. |
| Locales | Language and regional variants for localized Contentful fields. | Localized storefronts, search indexes, customer-experience applications, and translation workflows | Martini applies configured locale and fallback rules and avoids silently replacing one locale with another. |
Authentication and security considerations
Contentful authentication
Contentful uses different credentials by API and use case. Delivery and Preview API tokens retrieve published or preview content, while the Content Management API supports personal access tokens and OAuth 2.0 for delegated applications.
Secrets and permissions
Store Contentful tokens, OAuth credentials, and webhook secrets in Martini secrets or secured environment configuration. Access is constrained by the token, space, environment, organization, and Contentful roles or permissions.
- Use separate configuration for development, staging, and production environments.
- Restrict Martini endpoints that receive Contentful webhook requests.
- Validate webhook security according to the configured Contentful mechanism.
- Use the least-privileged Contentful access appropriate to each workflow.
Operational considerations for Contentful integrations
Reliability and scale
Contentful APIs apply rate limits and return paginated collections. Martini workflows should control concurrency, honor retry guidance for HTTP 429 responses, and follow pagination metadata rather than assuming a single response is complete.
Content lifecycle
Delivery, Preview, and Management APIs represent different lifecycle states. Content types can change, localized fields require explicit fallback rules, and Asset uploads may require processing or publishing before downstream use.
Synchronization controls
- Persist Sync API tokens only after successful processing.
- Use Contentful IDs, versions, or event identifiers to support idempotency.
- Do not rely on webhook ordering; retrieve current authoritative state.
- Implement explicit handling for deleted Entries and Assets.
- Test GraphQL queries when content-model fields or nullability change.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration instead of isolated scripts
Martini provides a maintainable workflow layer between Contentful and enterprise applications. It can combine webhook triggers, scheduled synchronization, REST or GraphQL calls, database checkpoints, transformations, validation, and downstream writes in one observable process.
Centralized controls
Reusable workflows keep authentication, environment selection, locale rules, lifecycle checks, idempotency, retries, and error handling consistent across integrations. A Martini API façade can also prevent every consuming application from implementing Contentful-specific security and management behavior.
- Map Contentful JSON into canonical and target-specific models.
- Recover from rate limits and transient downstream failures.
- Reconcile missed webhook activity with Sync API checkpoints.
- Monitor workflow outcomes and troubleshoot failed content deliveries.
Frequently asked questions
Contentful can integrate through its REST APIs for delivery, preview, management, synchronization, and image operations; its GraphQL Content API for selective queries; selected-event webhooks; and the Sync API for incremental published-content synchronization. Assets are managed through Contentful's asset model, while supported bulk actions are available for selected management operations.
Yes. Martini can consume Contentful REST and GraphQL APIs, receive selected Contentful webhook notifications, run scheduled Sync API workflows, transform Entries and Assets, and expose controlled APIs that call the Content Management API.
No. A dedicated Contentful connector is not required. Martini can use Contentful's confirmed native REST APIs, GraphQL API, selected-event webhooks, Sync API, authentication methods, and Content Management API through workflows and APIs.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Contentful. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Contentful, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
Use the Delivery API for published content, the Preview API for unpublished content, the Management API for supported administrative and content mutations, the Sync API for incremental published-content synchronization, and GraphQL when consumers need selective query-specific content. Asset operations use Contentful's Asset model and APIs.
Yes. Contentful supports webhook notifications for selected entry, asset, and publishing-related events, and Martini can receive them through an HTTP endpoint or workflow. Webhooks should trigger retrieval of the current object and should not be treated as a complete all-events synchronization mechanism.
For comprehensive incremental synchronization, a scheduled Martini workflow can use the Contentful Sync API and persist its returned token only after successful downstream processing. Webhook-driven workflows should use Contentful IDs and available event or version information for idempotency, retrieve authoritative state, and explicitly handle deletion and out-of-order delivery.
Yes. Martini can expose a secured REST API that validates internal requests, applies authorization and business rules, and calls Contentful's Content Management API. This can keep Contentful credentials private and centralize audit, environment, naming, version, and publishing controls.
Related Martini documentation
Workflows
Security
Connect Contentful with your enterprise systems
Use Martini to build reliable Contentful integrations around APIs, selected-event webhooks, incremental synchronization, content lifecycle rules, and secure enterprise workflows.