Webhooks

Webhooks let external systems send events to ORQO over HTTP. Any system that can make an HTTP POST request can integrate with ORQO via webhooks.

Inbound Webhooks

Each App has a unique webhook endpoint:

POST /api/v1/webhooks/:app_id

When ORQO receives a webhook:

1. The request is forwarded to the App's adapter for signature verification (POST /verify-webhook).
2. The payload is normalized by the adapter (POST /parse-inbound) into a standard format.
3. The sender is verified — only registered Contacts are accepted. Unknown senders are rejected.
4. The message is routed to the appropriate handler — either a waiting agent (waitbox) or Doorkeeper.

Signature Verification

Each platform uses its own signature mechanism. The adapter handles verification transparently — ORQO passes the raw request body and headers to the adapter's /verify-webhook endpoint.

Platform	Signature Header	Method
Slack	X-Slack-Signature	HMAC-SHA256 with signing secret
WhatsApp	X-Hub-Signature-256	HMAC-SHA256 with app secret
Telegram	X-Telegram-Bot-Api-Secret-Token	Secret token comparison
Custom	Configurable	Configurable algorithm

Requests with invalid signatures are rejected with no further processing.

Webhook Challenge Verification

Some platforms send a verification challenge when you first register a webhook URL:

• Slack sends a url_verification event with a challenge field. ORQO responds with the challenge value.
• WhatsApp (Meta) sends a GET request with hub.verify_token and hub.challenge parameters. ORQO verifies the token and responds with the challenge.

These challenges are handled automatically by the adapter's /parse-inbound response — the challenge_response field signals ORQO to echo the value back and stop processing.

Webhook Triggers (Workflow-Level)

For triggering workflows from external systems without an App, you have two options:

Webhook triggers provide a dedicated URL per workflow. No API key needed -- the URL token is the auth:

POST /api/v1/hooks/:token
Content-Type: application/json

{"event": "push", "branch": "main"}

Create webhook triggers from the Runs & Triggers tab on any workflow. ORQO generates the URL. See Reference: Triggers for details.

API trigger endpoint lets you trigger any workflow by ID using an API token:

POST /api/v1/trigger
Authorization: Bearer your-api-token

{"workflow_id": 42, "input": "..."}

See API for details.