Integration Patterns

This guide covers integration patterns for Agility CMS, including frontend frameworks, third-party services, and custom integrations.

Frontend Framework Integration

Next.js Integration

SDK: @agility/nextjs

Features:

• React Server Components support
• Automatic caching
• Preview mode support
• TypeScript support

Pattern:

import { getContentItem } from "@/lib/cms/getContentItem"

const { fields } = await getContentItem<IPost>({
  contentID: 204,
  languageCode: "en-us"
})

Other Framework Integrations

Gatsby:

• Static site generation
• GraphQL support
• Plugin-based architecture

Nuxt:

• Vue.js support
• Server-side rendering
• Module-based integration

Eleventy:

• Static site generation
• Template-based rendering
• Simple integration

API Integration Patterns

RESTful API

Pattern:

• Standard HTTP methods
• JSON responses
• Query parameters for filtering

Example:

GET /{instance-guid}/fetch/{locale}/list/posts?take=10&skip=0

GraphQL API

Pattern:

• GraphQL queries
• Type-safe queries
• Flexible data fetching

Example:

query {
  contentList(referenceName: "posts") {
    items {
      contentID
      fields {
        heading
        slug
      }
    }
  }
}

SDK Integration

Pattern:

• TypeScript SDK for type safety
• Automatic caching
• Preview mode support

Example:

const sdk = await getAgilitySDK()
const items = await sdk.getContentList({ referenceName: "posts" })

Third-Party Integrations

Analytics Integration

PostHog:

• Feature flags
• Analytics tracking
• A/B testing

Google Analytics:

• Page view tracking
• Event tracking
• Custom dimensions

Search Integration

Algolia:

• Full-text search
• Faceted search
• Search analytics

Custom Search:

• Build custom search
• Integrate with AI services
• Custom ranking

AI Integration

Azure OpenAI:

• AI-powered search
• Content generation
• Chat interfaces

Custom AI:

• Integrate custom AI services
• Build AI features
• Custom prompts

Webhook Integration

Webhook Pattern

Setup:

1. Configure the webhook in Agility CMS (Settings → Webhooks)
2. Create your webhook endpoint
3. Enable secure delivery and verify the signature on every request
4. Process the event idempotently and return a 2xx quickly

Event categories:

• Content Publish Events — content or a page is published or unpublished
• Content Save Events — content or a page is saved or deleted
• Content Workflow Events — content is requested for approval, approved, or declined

Delivery guarantees:

• Success is any 2xx; redirects count as failures and are not followed
• The delivery timeout is 30 seconds — acknowledge fast, work in the background
• Delivery is at-least-once; use the webhook-id header as an idempotency key
• Retries are opt-in per webhook (1–8 attempts, fast / standard / slow backoff)

⚠️ There is no webhook "security key." AGILITY_SECURITY_KEY is the preview key and is never sent with a webhook, and custom headers cannot be configured. Secure delivery signs each request instead — Agility implements the open Standard Webhooks spec, so you verify with an off-the-shelf library. See Verifying Signed Webhooks.

Webhook Handler

import { Webhook } from 'standard-webhooks'

export async function POST(request: Request) {
  // Read the RAW body - re-serializing the JSON breaks verification
  const raw = await request.text()

  const wh = new Webhook(process.env.AGILITY_WEBHOOK_SIGNING_SECRET!)
  try {
    wh.verify(raw, {
      "webhook-id": request.headers.get("webhook-id")!,
      "webhook-timestamp": request.headers.get("webhook-timestamp")!,
      "webhook-signature": request.headers.get("webhook-signature")!,
    })
  } catch {
    return Response.json({ error: "Invalid signature" }, { status: 401 })
  }

  const event = JSON.parse(raw)
  // Process event (idempotently - key off the webhook-id header)
  // Revalidate cache
  return Response.json({ ok: true })
}

Use each webhook's History view in Settings → Webhooks to see delivery attempts, response codes and errors when debugging an integration.

Custom Integration Patterns

Custom API Routes

Create custom API routes for:

• Custom business logic
• Third-party integrations
• Data transformations
• Custom workflows

Middleware Integration

Use middleware for:

• Preview mode handling
• Redirect management
• Locale routing
• Authentication

Best Practices

1. Use SDKs: Prefer SDKs over direct API calls
2. Type Safety: Use TypeScript for type safety
3. Error Handling: Handle errors gracefully
4. Caching: Leverage built-in caching
5. Security: Secure all integrations
6. Monitoring: Monitor integration health
7. Documentation: Document integration patterns