Custom Connectors

The 42 integrations under Integrations → PSA, RMM & Business Tools (and Xero, Microsoft 365, AWS, GCP and Alibaba above) are hand-written for one specific vendor each. Custom Connectors is the generic alternative: describe an arbitrary REST API yourself — base URL, authentication, and a set of callable actions — and Graften can call it without anyone writing Go code for your specific vendor.

Creating a connector

1. Go to Integrations → Custom Connectors → New Connector.
2. Give it a name and an HTTPS base URL (plain HTTP is rejected outright).
3. Pick an auth type:
   • None — no authentication header added.
   • API Key — a header (default Authorization, configurable) with an optional prefix (e.g. Bearer or Token ) plus your key.
   • Basic — a username and password, sent as HTTP Basic Auth.
   • Bearer — a static bearer token.
   • OAuth2 — a genuine authorization-code flow. You supply the authorize URL, token URL, client ID and client secret from an OAuth app you register with the third party yourself; Graften supplies one fixed callback URL (/api/v1/connectors/oauth/callback) that you register as the redirect URI on that app. Click Connect afterwards to complete the round-trip — the connector shows draft until that succeeds, then connected. API Key/Basic/Bearer/None connectors go straight to connected, since they need nothing further once saved.

Defining actions

Each connector can have any number of actions — one callable operation each, made of:

• Method (GET/POST/PUT/PATCH/DELETE) and path, appended to the base URL.
• Query parameters and headers, as key/value pairs.
• A body template for POST/PUT/PATCH.
• A response mapping — output keys mapped to dotted paths into the parsed JSON response (e.g. data.0.id). Leave it empty to get the whole parsed response back under response while you're still working out the shape.

Every field above (path, query values, header values, body) supports {{dotted.path}} placeholders, filled in from whatever variables are passed in at call time — a webhook payload, an automation event, or the sample variables you type into the Test panel. A path that doesn't resolve becomes an empty string rather than literal {{...}} text sent to the third party.

Testing and using a connector

The Test button on any action fires it immediately with sample variables and shows the raw mapped result and HTTP status — useful for working out the right response mapping before wiring anything real to it. Once it works, the same action can be called as a step in an Automation Rule (action kind connector_action) — see the Automation & Webhooks section — so a connector you build once can run unattended off whatever event triggers your rule.

A note on destinations

The destination URL is checked against the same SSRF guard used for outbound automation webhooks, both when you save an action and again every time it actually runs — a request cannot be redirected to an internal address after the fact by a DNS change.

API

GET/POST /api/v1/connectors, GET/PUT/DELETE /api/v1/connectors/{id}, GET/POST /api/v1/connectors/{id}/actions, PUT/DELETE /api/v1/connectors/{id}/actions/{actionId}, POST /api/v1/connectors/{id}/actions/{actionId}/test, GET /api/v1/connectors/{id}/oauth/connect (starts the OAuth2 round-trip).