HTTP Sink

The HTTP sink allows you to trigger workflow executions via standard HTTP requests. This is the most flexible sink type, supporting any HTTP method and custom paths.

Endpoint Format

POST/GET/PATCH/DELETE /sink/trigger/http/{app_id}/{path}

• app_id: Your application's unique identifier
• path: Custom path you configure (must start with /)

Configuration Options

| Field | Type | Description | Required | |-------|------|-------------|----------| | path | string | URL path for the endpoint (e.g., /webhook) | Yes | | method | string | HTTP method (POST, GET, etc.) | Yes | | auth_token | string | Optional Bearer token for authentication | No |

Local Mode

When running locally, the desktop app exposes an HTTP server on port 9657:

http://localhost:9657/{app_id}{path}

Example Request

curl -X POST "http://localhost:9657/app_abc123/webhook" \
  -H "Content-Type: application/json" \
  -d '{"event": "test", "data": {"key": "value"}}'

Remote Mode

When deployed to a server, the endpoint is publicly accessible:

https://your-domain.com/sink/trigger/http/{app_id}{path}

Example Request

curl -X POST "https://your-domain.com/sink/trigger/http/app_abc123/webhook" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-auth-token" \
  -d '{"event": "test", "data": {"key": "value"}}'

Authentication

Bearer Token

If you configure an auth_token, all requests must include it in the Authorization header:

curl -X POST "https://your-domain.com/sink/trigger/http/app_abc123/webhook" \
  -H "Authorization: Bearer your-secret-token" \
  -d '{"data": "payload"}'

Requests without the correct token will receive a 401 Unauthorized response.

No Authentication

If no auth_token is set, the endpoint is publicly accessible. Use this for:

• Webhooks from third-party services that can't add custom headers
• Development/testing environments

Caution

For production deployments, always use authentication when possible.

Response Format

The HTTP sink returns a streaming response with execution progress:

HTTP/1.1 200 OK
Content-Type: text/event-stream

data: {"type":"progress","run_id":"run_xyz","progress":25}

data: {"type":"progress","run_id":"run_xyz","progress":50}

data: {"type":"progress","run_id":"run_xyz","progress":100}

data: {"type":"complete","run_id":"run_xyz","output":{...}}

For non-streaming clients, the final result is included in the last event.

Use Cases

Webhook Receiver

Receive webhooks from external services like GitHub, Stripe, or Slack:

{
  "path": "/github-webhook",
  "method": "POST",
  "auth_token": null
}

API Endpoint

Create a custom API endpoint for your application:

{
  "path": "/api/v1/process",
  "method": "POST",
  "auth_token": "secret-api-key"
}

Form Handler

Handle form submissions from a website:

{
  "path": "/submit-form",
  "method": "POST",
  "auth_token": null
}

Error Handling

| Status Code | Description | |-------------|-------------| | 200 OK | Request accepted, execution started | | 401 Unauthorized | Invalid or missing auth token | | 404 Not Found | No matching sink found for path | | 500 Internal Server Error | Execution dispatch failed |

Best Practices

1. Use descriptive paths: /webhook/github/issues is better than /hook1
2. Enable authentication for production endpoints
3. Use HTTPS in production for encrypted communication
4. Monitor execution logs to track incoming requests
5. Set up rate limiting at the infrastructure level if needed