Integration Development

Connect external systems through GraphQL, tRPC, webhooks, and portal tokens. This guide follows version 3.1.7 (03acdf712c).

For auth headers, see Authentication. For email intake, see Email & Mail Worker.

Choose the contract

• UI reads and third-party queries: federated GraphQL at the gateway /graphql. See GraphQL API.
• Service-to-service: tRPC (/<service>/trpc) with httpBatchLink to the target's registered address. Never import another service's implementation.
• Agent tools: admit-only tRPC procedures via .meta({ agent }), called through /agent-tools/call. See Erxes Support Agent.
• Webhooks and custom HTTP: plugin expressRouter and apiHandlers in startPlugin, plus routes.ts files (for example Frontline mail intake).

Portal integrations

Websites use a Client Portal token (x-app-token) against cp* operations with a fixed server-side GraphQL document, as shown in the CMS Setup and SSR guides. Administrative Apps tokens (erxes-app-token) stay on the server behind an authorized interface. Do not build a generic GraphQL-forwarding endpoint that lets visitors execute arbitrary operations with the server credential.

GitHub sync (example)

backend/plugins/operation_api/src/modules/githubIntegration/ plus src/utils/githubClient.ts and githubWebhookHandler.ts show the full shape: store connection config, verify webhook signatures, map external milestones to local records, and reconcile on retry. Apply the same discipline to new integrations: verify signatures, validate payloads with Zod, enforce tenant scope, and make handlers idempotent.

Verify

1. Exercise the integration against staging with valid, invalid, and replayed payloads.
2. Confirm tenant isolation and permission failures are logged without leaking secrets.
3. Confirm retries converge (no duplicates).

Source references

• Plugin bootstrap handlers.
• GitHub webhook handler (example).