Plain

Overview

Self-hosted Plain uses the same connector flow as hosted ctxpipe. Plain has no OAuth application for other products, so an org admin pastes the API key of a Plain machine user in the setup. ctxpipe encrypts the key and the webhook token on the connection with the connection secret key of the deployment.

There is no PLAIN_* environment variable. You do not need to change Compose, Railway, or CDK settings.

What you need

• A public HTTPS AUTH_BASE_URL for the webhook target. Plain sends webhooks only to a public HTTPS address. Without it, the connector syncs once a day and on Sync now. ctxpipe cannot check that Plain reaches the URL: when Plain accepts the target but cannot reach it, the card still shows live updates as on.
• A ctxpipe GitHub App connection with write access to each Workspace repository that syncs Plain content.
• The backend and worker able to reach core-api.uk.plain.com over HTTPS.

Webhook target

At connect, ctxpipe creates one Plain webhook target for each connection:

{AUTH_BASE_URL}/api/v1/webhook/plain/{connectionId}

The target sends timeline.timeline_entry_changed events with a random token in the X-Ctxpipe-Webhook-Token header. ctxpipe compares the token and refuses a request without it. A failed enqueue returns 503, and Plain sends the event again.

Verify the connector

1. Open Connectors → Add connection → Plain.
2. Paste the API key of a machine user with the permissions that the setup lists.
3. In the Add to Workspaces step, select a Workspace and at least one Help Center or label. Merge the pull request that adds the source file under sources/plain/.
4. Confirm the source shows OK in the Workspace settings and files appear under plain/.
5. In Plain, open Settings → Webhooks and confirm the ctxpipe target. Add a note to a real thread with a selected label, not a Plain test thread. Confirm that POST /api/v1/webhook/plain/{connectionId} returns 200, and that the thread file changes after the 10-minute window.

See Plain connector for the files, the sync, and product troubleshooting.