Integrations & imports

Use the API and webhooks

Read support data or connect event-driven workflows without confusing their permissions.

Use the Conversation API when your integration needs to read stored support data. Use webhooks when another system should react to new conversation activity. Each has its own credentials and permissions.

Create a read-only API key

Open Settings → API as an owner or administrator. Name the key, select its inboxes, and decide whether to include private notes, unsent drafts, and their attachments. Private-content access is off by default.

Copy the key once and keep it in your server’s secret storage. Keys expire after 90 days and can be revoked in Settings. To change access or rotate a key, create a replacement and revoke the old one.

The API lists inboxes, conversations, chronological messages, and attachment metadata. Attachment downloads use separately authorized short-lived URLs. List endpoints use cursor pagination; follow each next cursor until it is empty.

The API does not send replies or modify records. See the Conversation API reference for authentication, endpoints, filters, response examples, rate limits, and error handling.

Add an event webhook

Open Settings → Webhooks, add a public HTTPS endpoint, and select conversation.created, reply.added, or both. For n8n, use the workflow’s production webhook URL.

Copy the one-time signing secret into the receiving system’s secure credentials. Send a test event and check delivery status before relying on the workflow.

A reply.added event contains the triggering reply, not the full thread. Events may arrive more than once or out of order, so the receiving workflow needs duplicate handling.

Verify incoming events

Your receiver should verify X-OutcomeArc-Signature against the exact raw body, using HMAC-SHA256 over timestamp + "." + raw_body. The signature has a v1= prefix; the timestamp comes from X-OutcomeArc-Timestamp.

Use a timing-safe comparison, reject timestamps outside your accepted window, and deduplicate X-OutcomeArc-Delivery before taking action. Return a 2xx response promptly. Delivery times out after 10 seconds, doesn’t follow redirects, and retries failed attempts.

Allow a workflow to read or write back

Per-endpoint permissions can separately allow conversation reads and draft/private-note write-back. Reading private notes requires an additional trusted scope; unsent drafts aren’t returned by webhook conversation reads.

Write-back creates plain-text drafts or private notes, not sent customer replies. Disable an endpoint or rotate its secret to revoke its old API access. Keep these webhook credentials separate from REST API keys and MCP tokens.

For a custom workflow that needs the scoped write-back contract, contact our team with the intended action and destination. Never include the credential in that request.

Browse all topics →

Still need a hand? Ask our team.