Skip to main content

Preparing your API for integrations

As you prepare to build integrations between your app and the other tools your customers use, it's critical to design your API with integrations in mind. This document covers best practices for making your API easy to integrate with, including authentication setup, webhook design, and API features that support integration builders.

Checklist

  • Set up seamless authentication on behalf of your customers
  • Implement webhooks to notify integrations when records change in your app
  • Design your API with features that support integrations, like pagination and incremental endpoints
  • Build a custom connector so your team members and customers can interact with your API in a workflow

Authentication​

Normally, the OAuth 2.0 Authorization Code flow is the best choice for authentication for integrations because your end user is presented a simple Connect button and easy authorization experience. If third-party services are integrating with your API, support for OAuth is essential.

Your users, though, will interact with your integration UI through the embedded marketplace or workflow builder while logged in to your app. Clicking a Connect button to connect to your app, from your app, may feel like a silly experience to your users.

We recommend supporting an authentication method that you, as the organization offering integrations, can set up on behalf of your customers. By supporting API keys, OAuth 2.0 Client Credentials, or another similar auth method, you as the organization can create an org-activated customer connection for each of your customers for your app.

If you activate a connection for your app for each of your customers, then when your customers go to set up an integration in your marketplace or workflow builder their authentication experience is seamless and simple - they're authenticated automatically by virtue of being logged into your app.

Webhooks​

You have two options for keeping downstream systems up-to-date with changes in your app:

  • Your app can emit webhooks requests when things change
  • Your integrations can poll your API for changes

Webhooks are the foundation of reliable, real-time integrations. Polling is slower and more resource-intensive.

We strongly recommend implementing webhooks in your app.

Emit events for meaningful state changes​

Emit a webhook event whenever a record is created, updated, or deleted. Think in terms of what downstream systems care about: if something changed that an integration might need to act on, emit an event for it.

Each event should include:

  • Event type - a stable, namespaced identifier like order.created or contact.updated
  • Timestamp - in UTC ISO 8601 format
  • Entity ID - so integrations can fetch the full record if needed
  • Payload - include the changed data or at minimum the fields that changed
  • Correlation / request ID - useful for debugging

Provide a webhook registration API​

Integrations need to register and deregister webhook subscriptions programmatically. Expose endpoints to:

  • Create a webhook subscription
    • Allow callers to specify the URL where events should be sent
    • Callers should specify an array of event types (like order.created, contact.updated) that they care about - don't send every event by default
    • Your API should respond with a unique subscription ID that can be used to manage the subscription later
  • List active subscriptions
  • Delete a subscription by ID

Prismatic's instance lifecycle handlers (webhookLifecycleHandlers.create and .delete) can call these endpoints automatically when customers enable or remove an integration or add a trigger to a workflow. This means webhook subscriptions are provisioned and cleaned up without any manual steps.

Sign your webhook payloads​

Include an HMAC signature on every webhook delivery so integrations can verify the payload is authentic. The standard approach is to include a header like X-Signature-256 with an HMAC-SHA256 hash of the request body, signed with a shared secret.

Prismatic supports HMAC signature verification in webhook triggers, and your custom connector's trigger can include custom logic to handle your implementation of HMAC.

API design for integrations​

A few API design choices make a significant difference when integrations are consuming your API at scale.

Support pagination and filtering​

Integrations often fetch large record sets. Implement cursor-based or offset pagination, and support filtering by:

  • Last modified timestamp (essential for incremental sync)
  • Customer or tenant scope
  • Resource type

Filtering by last modified timestamp allows integrations to fetch only records that changed since the last run, rather than pulling everything every time.

Provide incremental (delta) endpoints​

A dedicated endpoint that returns records changed since a given cursor or timestamp is one of the most valuable things you can build for integrations. It enables efficient polling as a fallback when webhooks aren't available, and makes initial sync and reconciliation straightforward.

Publish an OpenAPI schema​

An OpenAPI (formerly Swagger) specification is useful for integration builders - it documents your endpoints, request/response shapes, and authentication requirements in a machine-readable format. It also makes it faster to build and update a custom connector or code-native integration.

Build a custom connector​

A custom connector is a reusable Prismatic component that wraps your API. It lets you (and your customers) build integrations using your app's actions and triggers in the low-code designer, without writing boilerplate HTTP calls in every integration.

Building a connector for your own API is the best way to expose your platform's capabilities to integration builders. You define the actions (like "Create order" or "Update contact"), the authentication configuration, and the webhook triggers - and integration builders can use them like any other component.

A good custom connector for your app typically includes:

  • Actions for your core create, read, update, and delete operations
  • Triggers that receive and verify your webhook payloads, with lifecycle handlers to register and deregister subscriptions. You may have a "New Order" trigger that fires when your app emits an order.created event, for example.
  • A connection that supports org-activated connections for seamless authentication

See the custom connector documentation to get started. The wrap an API tutorial walks through building a connector from scratch.