Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hypha-docs.plinqx.app/llms.txt

Use this file to discover all available pages before exploring further.

Inbound webhooks let external systems trigger your flows by sending HTTP requests to Plinqx. Configure webhook triggers in your flows to receive data from external services.

​
Overview

Inbound webhooks enable:
  • External Integration: Receive data from external services
  • Event-Driven Flows: Trigger flows based on external events
  • Flexible Endpoints: Custom webhook paths for each flow
  • Secure Authentication: HMAC or API key authentication
  • Sync or Async: Choose response mode based on your needs

​
How Inbound Webhooks Work

1

Configure Webhook Trigger

Add a webhook trigger to your flow in the Flow Designer.
2

Get Webhook URL

Plinqx generates a unique webhook URL for your flow.
3

External System Calls

External system sends HTTP request to your webhook URL.
4

Flow Executes

Flow receives the request data and executes.
5

Response Sent

Flow returns response to the caller (sync) or acknowledges (async).

​
Configuring Webhook Triggers

1

Open Flow

Navigate to your flow in the Flow Designer.
2

Configure START Node

Click on the START node and select Webhook trigger type.
3

Set Webhook Path

Configure the webhook path (e.g., /production/v1, /staging/webhook).
Webhook paths must be unique within your tenant. Paths must start with / and cannot be just /.
4

Configure Settings

Set:
  • HTTP Methods: Which methods to accept (POST, GET, PUT, PATCH, DELETE)
  • Authentication: HMAC, API Key, or None
  • Response Mode: Sync (wait for result) or Async (acknowledge immediately)
  • Response Format: Wrapped or raw output format
5

Save Flow

Save and publish your flow to activate the webhook.

​
Webhook URL Format

Your webhook URL follows this format: 
https://hypha-api.plinqx.app/api/webhooks/flows/{flowId}{webhookPath}
Example: 
https://hypha-api.plinqx.app/api/webhooks/flows/flow_abc123/production/v1
The webhook URL is automatically generated when you configure a webhook trigger. Copy it from the flow configuration.

​
Authentication Methods

​
HMAC Authentication

HMAC (Hash-based Message Authentication Code) provides secure webhook verification:
1

Enable HMAC

Select HMAC as the authentication method.
2

Get Secret

Plinqx generates a webhook secret. Copy this secret.
3

Configure External System

Configure your external system to sign requests with the secret.
HMAC Signature Format: The signature is calculated as: 
HMAC-SHA256(timestamp + request_body, secret)
Include in headers:
  • X-Webhook-Signature: The HMAC signature
  • X-Webhook-Timestamp: Unix timestamp

​
API Key Authentication

Use API key authentication for simpler integration:
1

Enable API Key

Select API Key as the authentication method.
2

Set API Key

Enter your API key value.
3

Configure External System

External system includes API key in Authorization: Bearer {key} header.

​
No Authentication

For development or internal systems, you can disable authentication:
Only use no authentication for internal systems or development. Never expose unauthenticated webhooks publicly.

​
Response Modes

​
Async Mode (Default)

Async mode acknowledges the request immediately and processes the flow in the background:
  • Response: Immediate 202 Accepted
  • Use Case: Long-running flows, fire-and-forget
  • Response Body: { "accepted": true, "flowRunId": "..." }

​
Sync Mode

Sync mode waits for the flow to complete before responding:
  • Response: Flow execution result
  • Use Case: Need immediate response, short-running flows
  • Timeout: 30 seconds (configurable)
Sync mode is useful when the caller needs the flow result immediately. Use async for long-running flows.

​
Response Formats

​
Wrapped Format (Default)

Returns a structured response: 
{
  "success": true,
  "flowRunId": "frun_abc123",
  "output": {
    "result": "Flow output data"
  }
}

​
Raw Format

Returns just the END node output directly: 
{
  "result": "Flow output data"
}

​
HTTP Methods

Webhook triggers support multiple HTTP methods:
  • POST: Most common, sends data in request body
  • GET: Query parameters and headers only
  • PUT: Full resource update
  • PATCH: Partial resource update
  • DELETE: Resource deletion
Configure which methods your webhook accepts. Multiple methods can be enabled.

​
Input Mapping

Map webhook request data to flow inputs:
  • Query Parameters: Access via query.paramName
  • Headers: Access via headers.HeaderName
  • Body: Access via body.fieldName
  • Path Variables: Access via path.variableName

​
Calling Webhooks

​
Example: POST Request

curl -X POST 'https://hypha-api.plinqx.app/api/webhooks/flows/flow_abc123/production/v1' \
  -H 'Content-Type: application/json' \
  -H 'X-Webhook-Signature: {signature}' \
  -H 'X-Webhook-Timestamp: {timestamp}' \
  -d '{
    "data": "your payload"
  }'

​
Example: GET Request

curl -X GET 'https://hypha-api.plinqx.app/api/webhooks/flows/flow_abc123/production/v1?param=value' \
  -H 'X-Webhook-Signature: {signature}' \
  -H 'X-Webhook-Timestamp: {timestamp}'

​
Managing Inbound Webhooks

​
Viewing Active Webhooks

1

Navigate to Webhooks

Go to Webhooks → Inbound (or view in Flow Designer).
2

View List

See all active inbound webhooks with their paths and flows.

​
Testing Webhooks

Test your webhook triggers:
1

Open Flow

Navigate to your flow.
2

Test Trigger

Use the test panel to simulate webhook requests.
3

Verify Execution

Check flow execution logs to verify webhook processing.

​
Security Best Practices

Use HMAC

Always use HMAC authentication for production webhooks

Rotate Secrets

Periodically rotate webhook secrets

Validate Inputs

Validate and sanitize webhook inputs in your flows

Monitor Access

Monitor webhook access in audit logs

​
Error Handling

Webhook errors return appropriate HTTP status codes:
  • 404 Not Found: Invalid webhook path or flow not found
  • 405 Method Not Allowed: HTTP method not configured
  • 401 Unauthorized: Authentication failed
  • 400 Bad Request: Invalid request format
  • 500 Internal Server Error: Flow execution error

​
Next Steps

Flow Triggers

Learn about all trigger types

Flow Designer

Build flows with webhook triggers