API & Endpoints

Trigger URL

Each connector endpoint has a unique trigger URL in this format:

Send a JSON payload via POST to this URL to trigger the connector. The request body becomes the $payload context available in all expressions.

Authentication

Every request to the trigger URL must be authenticated using one of the following methods. At least one valid token is required.

curl -X POST https://your-domain/api/v1/connectors/1/trigger \
  -H "Authorization: Bearer your-bearer-token-here" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

curl -X POST https://your-domain/api/v1/connectors/1/trigger \
  -H "X-Secret-Token: your-secret-token-here" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

Origin Validation

Optionally restrict which domains can send requests to your endpoint by configuring an allowed URLs whitelist. When configured, the middleware checks the Origin or Referer header against the whitelist.

If no allowed URLs are configured, origin validation is skipped and requests from any origin are accepted (as long as they have a valid token).

Webhook Signature Verification

For additional security, you can configure a webhook secret on your connector. When set, Krosyn verifies the HMAC-SHA256 signature of the request body against the X-Webhook-Signature header.

# The signature is the HMAC-SHA256 hex digest of the raw request body
signature = HMAC-SHA256(webhook_secret, request_body)

# Send it in the header
X-Webhook-Signature: {signature}

If the connector has a webhook secret but the request is missing the signature header, or the signature does not match, the request is rejected with a 401 error.

Token Expiry

Endpoint tokens can optionally have an expiry date. After the expiry date, all requests to the endpoint are rejected with a 401 error, regardless of whether the token is correct. To restore access, rotate or regenerate the tokens from the connector settings.

An email notification is sent to organization admins when tokens are within 7 days of expiry.

Integration Examples

The connector detail page provides ready-made code examples for integrating with your endpoint. Examples are available in cURL, JavaScript, and Python.

• Each example includes the correct authentication headers and a sample payload
• Use the copy button to copy any example to your clipboard
• Examples update automatically when tokens are rotated

Loop Prevention

Krosyn automatically detects and prevents infinite connector loops. When a connector's Perform step triggers another Krosyn connector, it forwards an execution depth header. If the depth exceeds the maximum (default: 5 levels), the request is rejected with a 429 status code.

This prevents scenarios where Connector A triggers Connector B, which triggers Connector A again, creating an infinite loop.

Rate Limiting

The trigger endpoint is rate-limited to prevent abuse. If you exceed the rate limit, requests return a 429 status code.

Both limits apply simultaneously. The per-connector limit helps prevent loops where connectors trigger each other rapidly.

Response Format

Successful trigger requests return a JSON response with the execution result:

{
  "status": "completed",
  "event_id": 42,
  "response_code": 200
}

Possible status values:

• completed - All steps executed successfully
• skipped - Trigger condition evaluated to false
• failed - An error occurred during execution

Error Codes