Skip to main content

Configure Webhooks

Set up webhook endpoints so external platforms can send events to ORQO. Inbound webhooks allow apps to receive messages, notifications, and trigger actions based on external events.

Prerequisites​

  • An app with the "Receive" capability configured (see Set Up an App)
  • The external platform must support outbound webhooks

Steps​

1. Understand the webhook architecture​

When an external platform sends a webhook to ORQO, the request flows through:

External Platform → POST /api/v1/webhooks/:app_id → Rails → Doorkeeper/Processing

Each app gets a unique webhook URL based on its ID. The platform sends events to this URL, and ORQO routes them to the correct app for processing.

2. Find your app's webhook URL​

Navigate to Settings > Apps and click your app card. The webhook URL is displayed in the app details:

https://your-orqo-domain.com/api/v1/webhooks/:app_id

Copy this URL -- you will paste it into the external platform's webhook configuration.

Webhook URL in app settings

3. Register the webhook URL with the external platform​

Go to the external platform's settings and add a new webhook endpoint:

Slack:

  1. Open your Slack app's settings at api.slack.com
  2. Navigate to Event Subscriptions
  3. Paste the webhook URL as the Request URL
  4. Subscribe to the events you want (e.g., message.channels, app_mention)

GitHub:

  1. Open repository Settings > Webhooks
  2. Add the webhook URL as the Payload URL
  3. Set content type to application/json
  4. Select which events to receive

Custom services:

  1. Add the webhook URL to the service's outbound webhook configuration
  2. Ensure the service sends JSON payloads via POST

4. Configure signature verification​

To ensure webhook requests are authentic, configure signature verification in the app's Receive Config:

{
  "signature_header": "X-Hub-Signature-256",
  "signature_algorithm": "hmac-sha256",
  "signature_secret_field": "signing_secret"
}

The signature secret is read from the app's credentials or app config. ORQO validates the signature on every inbound request and rejects requests that do not match.

info

Signature verification protects against spoofed webhook calls. Always enable it for production apps.

5. Configure event parsing​

The Receive Config tells ORQO how to extract meaningful data from the webhook payload:

{
  "message_path": "event.text",
  "sender_path": "event.user",
  "channel_path": "event.channel",
  "event_type_path": "event.type"
}

These JSON paths map fields in the incoming payload to ORQO's internal message format.

6. Handle webhook challenges​

Some platforms (notably Slack) send a verification challenge when you first register a webhook URL. ORQO handles these automatically -- the webhook endpoint responds to url_verification challenges without additional configuration.

7. Test the webhook​

Send a test event from the external platform (most platforms have a "Send Test" button in their webhook settings). Then check:

  1. App status -- Should remain "Verified"
  2. Channel messages -- The inbound message should appear in the app's message log
  3. Doorkeeper conversations -- If the app routes to Doorkeeper, a conversation should be created
tip

Use the external platform's webhook delivery log to see request/response details if messages are not arriving. Common issues: incorrect URL, firewall blocking, signature mismatch.

8. Route inbound messages​

Inbound webhook messages can be routed to:

  • Doorkeeper -- ORQO's conversational AI interface processes the message and responds
  • Workflow trigger -- The message triggers a specific workflow run
  • Waitbox -- The message is held for pickup by a running workflow that is awaiting user input

Routing is configured in the app's receive config and depends on your use case.

9. Monitor webhook activity​

Review inbound webhook activity in the app's Channel Messages section. Each message shows:

  • Timestamp
  • Sender information
  • Message content
  • Processing status (delivered, pending, error)

What's next​

Learn more​