Creating a Connector

Step 1: Basic Information

Navigate to the Connectors page and click Create Connector. Fill in the basic details:

• Name (required): A descriptive name, e.g. "Slack Order Notifications"

Step 2: Example Payload

Paste a sample JSON payload that represents the data your connector will receive. This is used for:

• Autocomplete suggestions when writing expressions (fields from the payload appear as suggestions)
• Testing expressions before saving
• Documenting the expected data format

{
  "event_type": "order.created",
  "order": {
    "id": "ORD-12345",
    "total": 89.99,
    "currency": "USD",
    "customer": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "items": [
      { "name": "Widget", "quantity": 2, "price": 29.99 },
      { "name": "Gadget", "quantity": 1, "price": 30.01 }
    ]
  }
}

Step 3: Configure the Trigger

The trigger determines when your connector should run. It is a single expression that must evaluate to a truthy value. If it evaluates to false, the connector is skipped.

If you leave the trigger empty, the connector runs on every incoming request.

Step 4: Configure the Process Step

The process step is optional. Use it when you need to:

• Fetch additional data from an external API (e.g. customer details from a CRM)
• Transform or combine fields before the perform step

External API Lookup

Configure a lookup URL, optional headers, and query parameters. Expressions can be used in all of these fields. The response is available as $lookup in subsequent fields.

Field Mappings

Add key-value pairs where the key is the output field name and the value is an expression. Fields are evaluated sequentially, so later fields can reference earlier ones via $processed.field_name.

Step 5: Configure the Perform Step

The perform step sends an HTTP request to a target API with your transformed data.

• API URL (required): The target endpoint. Can contain expressions, e.g. https://api.slack.com/webhooks/$secret.SLACK_WEBHOOK_ID
• HTTP Method: POST, PUT, PATCH, or DELETE (defaults to POST)
• Custom Headers (optional): Key-value pairs, values can be expressions
• Request Body Fields: Key-value pairs that form the JSON body. Each value is an expression.

Step 6: Set Up the Endpoint

When you create a connector, an endpoint is automatically provisioned with a unique trigger URL and authentication tokens. The endpoint provides:

• A unique trigger URL in the format POST /api/v1/connectors/{id}/trigger
• Auto-generated bearer token and secret token for authentication
• Optional allowed URLs for origin restriction (configurable after creation)

The tokens are displayed once when the connector is created. Copy and store them securely before navigating away.

Step 7: Test Your Connector

Test Run (In-App)

The fastest way to test your connector is with the built-in Test Run feature. On the connector detail page, click the Test Run button to execute the full pipeline using your example payload data.

• Runs the complete Trigger, Process, and Perform pipeline end-to-end
• Works on disabled connectors, so you can test while configuring
• If you have unpublished draft changes, you can toggle between testing the draft or published config
• Results are shown inline with status, response code, and duration
• Test runs appear in the Events history with a "Test" badge
• Test runs count towards your monthly event limit

The Test Run button requires an example payload to be configured (Step 2). If your connector has no example payload, the button will be disabled.

Manual HTTP Request

Alternatively, you can send a test request using cURL, Postman, or any HTTP client:

curl -X POST https://your-krosyn-url/api/v1/connectors/1/trigger \
  -H "Authorization: Bearer your-bearer-token" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "order.created",
    "order": {
      "id": "ORD-12345",
      "total": 89.99,
      "customer": {
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe"
      }
    }
  }'

Check the Events tab on the connector detail page to see the execution result, including the request sent to the target API and the response received.

Editing Connectors

To edit an existing connector, open it from the Connectors list and click Edit. The edit form uses the same layout as the creation form.

The connector name and example payload update immediately when saved. Configuration fields (trigger, process, perform, and their related settings like retry and headers) are saved as a draft until you explicitly publish them. This lets you modify a connector's pipeline without affecting live execution. You can test draft changes using the Test Run feature before publishing. When you are ready, click Publish to apply the draft to the live connector.

Enabling and Disabling

New connectors start as disabled. You must enable a connector before it can process incoming requests. Use the toggle on the connector detail page to switch between enabled and disabled.

Disabled connectors still have active endpoints, but incoming requests are rejected during execution.

Cloning a Connector

To clone a connector, open the More menu on the connector detail page and select Clone.

• The clone is named "Copy of {original name}" and starts disabled
• A new endpoint with fresh tokens is provisioned automatically
• All configuration (trigger, process, perform) is copied as-is

Bulk Operations

Select multiple connectors from the list page to perform bulk actions:

• Bulk enable or disable selected connectors
• Bulk delete selected connectors (requires confirmation)

Expression Testing

Expression inputs in the connector form have an inline test feature. Click the test button next to an expression field to evaluate it against the connector's example payload. The result is displayed inline.

Expression testing is rate limited to 30 tests per minute.