.png)
Contentstack Integration Guide
Connect Contentstack content, assets, and publishing events with enterprise applications through REST, GraphQL, webhooks, and Martini workflows.
Contentstack integration options at a glance
Contentstack provides REST APIs for content delivery, content management, publishing-related actions, assets, environments, locales, and releases. Its GraphQL Content Delivery API supports selective queries of published content, including related and nested fields. Webhooks provide notifications for selected content, publishing, and asset events, while bulk operations support certain management actions. Asset endpoints handle media and files. Martini can consume these APIs, receive webhook requests through an API or workflow entry point, map Contentstack JSON into target models, apply business rules, and run scheduled reconciliation workflows. Delivery tokens, management tokens, user tokens, API keys, and applicable OAuth credentials can be stored securely in Martini.
| Integration point | Supported by Contentstack? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Contentstack REST APIs support content delivery and management, including Entries, Assets, Content Types, Environments, publishing-related actions, locales, and releases. | Martini can consume the REST endpoints from workflows, expose APIs around them, map JSON payloads, and orchestrate calls to downstream systems. |
| GraphQL APIs | Yes | The GraphQL Content Delivery API retrieves published content with selective fields, nested structures, and related Entries in a query. | Martini can submit version-controlled GraphQL queries and variables, transform the response, and combine GraphQL retrieval with REST management operations. |
| Webhooks / outbound callbacks | Limited | Contentstack webhooks notify external endpoints for selected content, publishing, deletion, and asset-related events. | Martini can expose an API or workflow entry point, validate the request, retrieve the authoritative object, and route the event with duplicate and ordering controls. |
| Bulk / async / batch APIs | Limited | Bulk operations are available for selected Content Management API actions, but coverage is operation-specific and does not apply to every resource. | Martini can orchestrate bounded batches, checkpoint progress, retry transient failures, and record partial results for replay. |
| File / asset APIs | Yes | Contentstack Asset APIs support uploading, updating, retrieving, and deleting media and file objects and managing asset metadata and URLs. | Martini can handle metadata and file-oriented API calls, map asset references, and coordinate transfers with media or commerce platforms. |
| Authentication | Yes | Contentstack uses Stack API keys and delivery tokens for delivery, management tokens or user tokens for management, and OAuth 2.0 where enabled for applicable scenarios. | Martini can store credentials in secrets or protected environment configuration and apply separate delivery, preview, and management credentials. |
| Scheduled synchronization | Yes | Scheduled API retrieval supports initial loads, periodic reconciliation, and recovery where webhook coverage is incomplete or events are missed. | Martini scheduler-triggered workflows can paginate through Entries and Assets, persist checkpoints, and apply bounded concurrency and retry rules. |
| Database access | No | Contentstack is a managed SaaS platform and direct database access is not an expected integration mechanism. | Martini should use Contentstack REST APIs, GraphQL Content Delivery, webhooks, and asset endpoints instead of direct database connectivity. |
How Contentstack exposes data and business events
Contentstack REST APIs
Contentstack REST APIs provide the main interface for content delivery and management. They cover Entries, Assets, Content Types, Environments, locales, releases, publishing-related actions, and other permitted management resources.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates with the appropriate delivery or management credentials, retrieves or changes the required Contentstack resource, validates the response, maps the JSON model, and continues orchestration with the target system.
Implementation sequence
Contentstack GraphQL Content Delivery API
Contentstack's GraphQL Content Delivery API is designed primarily for querying published content. It can return selected fields and related content in a single query, while management operations should remain on the appropriate REST APIs.
Martini implementation pattern
Martini implementation pattern: a workflow submits a controlled GraphQL query with Stack, environment, locale, and delivery credentials, transforms the response into a canonical model, and sends only the required content to downstream applications.
Implementation sequence
Contentstack Webhooks
Contentstack webhooks provide notifications for selected content, publishing, deletion, and asset-related events. Coverage depends on the configured event type and should not be assumed to include every platform action.
Martini implementation pattern
Martini implementation pattern: a Martini API or workflow entry point receives and validates the notification, identifies the affected Stack and object, retrieves the current authoritative resource through REST or GraphQL, and routes the result to downstream systems with idempotency and reconciliation controls.
Implementation sequence
Contentstack Asset APIs
Contentstack Asset APIs support file and media operations, including upload, metadata updates, retrieval, association with Entries, and deletion. Integrations should define whether Contentstack or an external DAM owns each asset attribute.
Martini implementation pattern
Martini implementation pattern: a workflow retrieves the asset metadata or file as required, applies content-type and size rules, transfers or references the asset in the target platform, and records stable identifiers and processing status.
Implementation sequence
Contentstack Bulk Operations
Contentstack supports bulk operations for selected Content Management API actions. Availability is operation-specific, so workflows must not assume that every Entry, Asset, or administrative action supports asynchronous bulk processing.
Martini implementation pattern
Martini implementation pattern: Martini partitions a large job into bounded batches, submits supported bulk operations, tracks progress and partial results, and uses individual API calls or reconciliation for items that fail.
Implementation sequence
Common Contentstack integration patterns
Pattern 1: Index published content in Algolia
When to use this pattern
Use this pattern when published Contentstack Entries must become searchable quickly. A webhook starts the flow, but the workflow retrieves the current Entry so that duplicate, delayed, or incomplete notifications do not produce stale index data.
Integration direction
Example Mapping
| Contentstack Field | Canonical Field | Target Field |
|---|---|---|
| Entry.uid | content.externalId | objectID |
| Entry.title | content.title | title |
| Entry.url | content.url | url |
| publish_details.locale | content.locale | locale |
Martini implementation pattern
Martini receives a selected publication event, validates its Stack and Environment, retrieves the Entry and required references through REST or GraphQL, transforms the payload into an Algolia document, and submits an idempotent indexing request. The workflow records the event and Entry identifiers, retries transient failures with backoff, and sends unrecoverable items to a replay or reconciliation path.
Martini capabilities used
- workflow triggers
- API consumption
- data mapping
- business rules
- idempotency
- error handling
Pattern 2: Trigger a website deployment
When to use this pattern
Use this pattern when an approved Contentstack publication should initiate a Netlify or Vercel rebuild. Environment checks are important so that development or preview activity does not trigger a production deployment.
Integration direction
Example Mapping
| Contentstack Field | Canonical Field | Target Field |
|---|---|---|
| event.type | publication.eventType | deployment.reason |
| environment.name | deployment.environment | deployment.target |
| Entry.uid | content.changeId | deployment.metadata |
Martini implementation pattern
A Martini API receives the Contentstack webhook, validates the event and webhook authenticity, checks the target Environment, and calls the appropriate deployment hook. Martini applies allow-list rules for production, records the deployment response, and retries transient HTTP failures without triggering duplicate deployments unnecessarily.
Martini capabilities used
- API exposure
- webhook handling
- workflow orchestration
- business rules
- secure configuration
- error handling
Pattern 3: Synchronize content with Shopify
When to use this pattern
Use this pattern when Contentstack owns product storytelling, merchandising, or campaign content that must be associated with Shopify resources. The implementation should define which system owns product facts, identifiers, and publication status.
Integration direction
Example Mapping
| Contentstack Field | Canonical Field | Target Field |
|---|---|---|
| Entry.uid | content.externalId | metafield.contentstack_uid |
| Entry.title | content.displayName | product.title |
| Entry.body | content.description | product.description |
| Asset.url | content.mediaUrl | product.media |
Martini implementation pattern
Martini consumes a Contentstack event or runs a scheduled synchronization, retrieves the current Entry and Assets, maps content types to Shopify resources, and applies source-of-truth and publication rules. It performs idempotent updates using stable identifiers, handles pagination for initial loads, and checkpoints partial failures for safe replay.
Martini capabilities used
- scheduled workflows
- API consumption
- data transformation
- mapping
- business rules
- checkpointing
Pattern 4: Coordinate Contentstack assets with Cloudinary
When to use this pattern
Use this pattern when Contentstack manages editorial references while Cloudinary manages media delivery, transformations, or renditions. It is suitable for workflows that need consistent metadata and controlled movement of approved files.
Integration direction
Example Mapping
| Contentstack Field | Canonical Field | Target Field |
|---|---|---|
| Asset.uid | asset.externalId | contextualMetadata.contentstack_uid |
| Asset.filename | asset.fileName | public_id |
| Asset.url | asset.sourceUrl | asset.source |
| Asset.content_type | asset.mimeType | resource_type |
Martini implementation pattern
Martini receives an asset event or retrieves Assets on a schedule, determines whether metadata, a binary file, or only a reference must be transferred, and calls the target media API. The workflow applies file-size and content-type validation, preserves stable identifiers, avoids unnecessary transfers, and routes failed transfers to a retry workflow.
Martini capabilities used
- webhook handling
- file and asset processing
- data mapping
- validation
- workflow orchestration
- retry handling
Applications commonly integrated with Contentstack
Contentstack commonly participates in composable web, digital commerce, search, media, and editorial workflows. Martini can orchestrate these integrations using Contentstack APIs and webhooks without requiring a dedicated native connector.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize selected product, campaign, or customer-facing content with Salesforce records or marketing workflows. | Contentstack → Martini → Salesforce | Receive a Contentstack webhook or run a scheduled retrieval workflow, fetch the authoritative Entry through the REST API, map approved fields to the Salesforce model, apply ownership and publication rules, and retry or reconcile failed writes. |
| Algolia | Index published articles, product content, and landing pages for site search. | Contentstack → Martini → Algolia | Receive a selected publication webhook, retrieve the current Entry and referenced data, transform it into an Algolia indexing document, submit the indexing request, and retain event and object identifiers for safe retries. |
| Netlify | Trigger a website rebuild or deployment after approved Contentstack content is published. | Contentstack → Martini → Netlify | Expose a Martini webhook endpoint, validate the Contentstack event, confirm the relevant environment and publication status, then call the configured Netlify deployment hook with controlled retry handling. |
| Vercel | Start a deployment or rebuild workflow when content changes are published to a web application. | Contentstack → Martini → Vercel | Route a Contentstack publication notification into a Martini workflow, apply environment and locale rules, invoke the Vercel deployment endpoint, and log the deployment request for reconciliation. |
| Shopify | Coordinate product storytelling, merchandising content, editorial content, or campaign data with Shopify resources. | Contentstack → Martini → Shopify | Retrieve changed Entries or run a scheduled synchronization, map Contentstack content types to Shopify resources, enforce source-of-truth rules, upsert target data, and isolate partial failures for replay. |
| Cloudinary | Coordinate media assets, metadata, transformation details, and delivery URLs between Contentstack and a media platform. | Contentstack → Martini → Cloudinary | Use Contentstack asset notifications or scheduled asset retrieval, compare stable identifiers and metadata, transfer only required files or references, and apply explicit ownership rules before updating either system. |
| Jira | Create or update operational issues for publication exceptions, review tasks, or editorial failures. | Contentstack → Martini → Jira | Receive a selected Contentstack event, evaluate workflow and validation rules, create or update a Jira issue with the Stack, Entry, environment, and failure context, and prevent duplicate issues with an external key. |
How to build a Contentstack integration in Martini
Objective
Establish the Contentstack API access required for delivery, management, GraphQL, webhooks, and asset operations.
Instructions in Martini
- Select delivery, preview, or management credentials for the use case.
- Store Stack API keys, delivery tokens, management tokens, user tokens, or OAuth credentials in Martini secrets or protected environment configuration.
- Separate credentials by Stack, Environment, and operational purpose where appropriate.
- Define the target application credentials using the same secure configuration approach.
Objective
Select an event-driven or scheduled entry point that matches the completeness and latency requirements of the integration.
Instructions in Martini
- Use a Martini API or workflow entry point for supported Contentstack webhook events.
- Use a scheduler-triggered workflow for initial loads, periodic reconciliation, and missed-event recovery.
- Confirm that the selected Contentstack webhook event covers the required content or asset change.
- Include Stack, Environment, locale, and object identifiers in the processing context.
Objective
Obtain the authoritative Contentstack payload rather than relying only on the webhook body.
Instructions in Martini
- Retrieve Entries or Assets through the Contentstack REST API when management or asset operations are required.
- Use the GraphQL Content Delivery API for selective published-content queries and related data.
- Handle pagination, localized fields, references, and optional fields explicitly.
- Record event identifiers, object UIDs, versions, or checkpoints where available.
Objective
Coordinate Contentstack calls, transformations, target writes, and recovery paths in a maintainable Martini workflow.
Instructions in Martini
- Separate receipt, retrieval, transformation, target writing, and completion states.
- Use bounded concurrency for large synchronization jobs.
- Add conditional routing for Environment, locale, publication status, and object type.
- Create a reconciliation or dead-letter path for events that cannot be completed immediately.
Objective
Convert Contentstack Content Types, Entries, Assets, and publishing metadata into the target system's model.
Instructions in Martini
- Map stable Contentstack identifiers to external identifiers in the target system.
- Transform nested, localized, referenced, and optional fields defensively.
- Map Asset URLs, metadata, or binaries according to the agreed ownership model.
- Validate required fields before performing downstream writes.
Objective
Prevent unintended publication, duplication, or cross-environment data movement.
Instructions in Martini
- Keep preview and non-production content out of production targets unless explicitly permitted.
- Apply source-of-truth rules for product, media, and publication fields.
- Use idempotency keys based on Stack, Environment, locale, object UID, version, and event identifiers where available.
- Distinguish content validation failures from transient service errors.
Common Contentstack data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Stack | Defines the Contentstack project boundary containing content models, Entries, Assets, Environments, locales, and configuration. | Salesforce, Shopify, Algolia, Jira, data stores | Martini uses Stack identifiers as part of routing, credential selection, idempotency, and reconciliation keys. |
| Content Type | Defines the schema and fields for content such as articles, products, landing pages, and author profiles. | Shopify, Salesforce, search indexes, website build systems | Martini validates and versions mappings against Content Type structure and handles optional or evolving fields defensively. |
| Entry | Represents a content item created from a Content Type, including localized and referenced content. | Algolia, Salesforce, Shopify, Netlify, Vercel | Martini retrieves the authoritative Entry through REST or GraphQL, maps fields and references, applies publication rules, and performs idempotent upserts. |
| Asset | Represents managed media or files with metadata and a file URL. | Cloudinary, Shopify, search indexes, website platforms | Martini synchronizes metadata or binary content as required, preserves stable identifiers, and applies file size, content-type, and ownership rules. |
| Environment | Separates development, staging, and production content-management contexts. | Netlify, Vercel, Salesforce, Shopify | Martini includes Environment in routing and synchronization keys and prevents preview or non-production content from reaching production targets unintentionally. |
| Release | Groups publishing actions that can be scheduled or executed together. | Deployment platforms, search indexes, operational workflows | Martini can process release-related notifications or retrieve release information through permitted APIs, then coordinate downstream publishing and reconciliation. |
Authentication and security considerations
Credential separation
Contentstack uses Stack API keys and delivery tokens for delivery requests, while management operations may use management tokens, user tokens, API keys, or OAuth 2.0 where enabled. Use separate delivery, preview, and management credentials where possible.
Secure configuration
Store Contentstack credentials in Martini secrets or protected environment configuration. Do not embed tokens in workflow definitions or expose them in logs, webhook responses, or transformed payloads.
Authorization boundaries
- Constrain access by Stack, Environment, locale, role, token, and API-specific permissions.
- Validate inbound webhook authenticity using the verification method configured for Contentstack.
- Prevent preview or draft content from reaching production targets unless explicitly authorized.
Operational considerations for Contentstack integrations
Throttling and pagination
Contentstack limits vary by API, plan, region, and operation. Use bounded concurrency, paginate Entry and Asset retrieval, and apply exponential backoff for eligible 429 and transient 5xx responses.
Idempotency and ordering
Webhook requests can be duplicated, delayed, or out of order. Use Stack, Environment, locale, object UID, version, and event identifiers where available, and retrieve the current authoritative object before downstream writes.
Schema and content variation
Content Types evolve and Entries can contain optional, localized, nested, or referenced fields. Validate required fields, version mappings when necessary, and test GraphQL queries against the target Stack and Environment.
Reconciliation and observability
Webhook delivery should not be treated as a complete change ledger. Schedule reconciliation workflows, checkpoint large jobs, capture request identifiers and object context, and route unrecoverable failures to a replay or dead-letter process.
Why use Martini instead of scripts or point-to-point integrations?
Orchestrate more than an API call
Martini coordinates Contentstack webhooks, REST and GraphQL retrieval, Asset handling, target writes, business rules, and reconciliation in explicit workflows rather than scattering logic across scripts.
Maintainable mappings
Mappings and transformations can normalize Contentstack Content Types, Entries, Assets, locales, and publishing metadata for different target applications while allowing validation and custom logic where required.
Reliable operations
Martini supports secure configuration, scheduled execution, conditional routing, checkpointing, retry handling, and operational logging. This provides a controlled foundation for duplicate events, rate limits, partial failures, schema changes, and environment separation.
Frequently asked questions
Contentstack can integrate through its REST APIs for delivery and management, its GraphQL Content Delivery API for published-content queries, webhooks for selected events, and Asset APIs for media and files. Scheduled workflows can support initial loads and reconciliation.
Yes. Martini can consume Contentstack REST and GraphQL APIs, receive supported webhook requests, handle Asset endpoints, store credentials securely, and orchestrate mappings, business rules, target writes, retries, and reconciliation workflows.
No. A dedicated Contentstack connector is not required. Martini can use Contentstack's documented REST APIs, GraphQL Content Delivery API, asset endpoints, webhook notifications, and authentication mechanisms.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Contentstack. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Contentstack, cloud infrastructure, or other third-party systems depending on subscription, usage, and deployment model.
Use REST for content management, Asset operations, publishing-related actions, and administrative resources. Use GraphQL when retrieving published content with selective, nested, or related fields. Both interfaces can be used in the same Martini workflow.
Yes. Martini can expose an API or workflow entry point for supported Contentstack webhook events. The implementation should validate requests, handle duplicate or out-of-order delivery, and retrieve the current object when the notification is incomplete or stale.
Webhook-driven flows should use stable identifiers, versions, or event identifiers for idempotency and should retrieve the authoritative Entry or Asset after notification. Scheduled reconciliation through REST or GraphQL can identify missed changes and repair downstream state.
Yes. Martini can expose controlled REST or other API endpoints that normalize Contentstack delivery or management operations, apply authorization and business rules, and hide vendor-specific payloads from downstream consumers.
Related Martini documentation
APIs
Transformation
Integrate Contentstack with Martini
Use Martini to connect Contentstack content, assets, and publishing events with enterprise applications through secure APIs, workflows, mappings, and reliable synchronization.