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 → Adapter (verify + parse) → 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's adapter for verification and normalization.

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.

3. Register the Webhook with the External Platform​

The registration process varies by platform:

Slack:

  1. Open your Slack app's settings at api.slack.com.
  2. Navigate to Event Subscriptions and enable events.
  3. Paste the webhook URL as the Request URL.
  4. Slack sends a url_verification challenge — ORQO handles this automatically.
  5. Subscribe to the events you want (e.g., message.im, message.channels, app_mention).

WhatsApp (Meta):

  1. Open your WhatsApp app in the Meta Developer portal.
  2. Navigate to Configuration > Webhook.
  3. Set the Callback URL to the webhook URL.
  4. Set the Verify Token to the value stored as WHATSAPP_VERIFY_TOKEN.
  5. Meta sends a GET verification challenge — ORQO verifies the token and responds.
  6. Subscribe to the messages webhook field.

Telegram:

  1. Use the Telegram Bot API to register the webhook: 
    curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook" \
      -H "Content-Type: application/json" \
      -d '{"url": "https://your-orqo-domain.com/api/v1/webhooks/:app_id", "secret_token": "your-secret"}'
  2. The secret_token is verified on every request via the X-Telegram-Bot-Api-Secret-Token header.

Custom services:

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

4. Signature Verification​

Each platform uses its own signature verification mechanism. ORQO delegates verification to the app's adapter — you don't need to configure signature details manually for supported platforms.

PlatformSignature HeaderHow It Works
SlackX-Slack-SignatureHMAC-SHA256 with signing secret
WhatsAppX-Hub-Signature-256HMAC-SHA256 with app secret
TelegramX-Telegram-Bot-Api-Secret-TokenSecret token comparison
CustomConfigurableSet up via adapter
info

Signature verification protects against spoofed webhook calls. All supported platform adapters verify signatures automatically when the correct credentials are assigned.

5. Handle Webhook Challenges​

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

  • Slack sends a POST with a url_verification event. ORQO responds with the challenge value automatically.
  • WhatsApp (Meta) sends a GET request with hub.verify_token and hub.challenge parameters. ORQO verifies the token and echoes the challenge.
  • Telegram does not use a challenge — the webhook is registered via an API call.

No manual configuration is needed for challenge handling.

6. Test the Webhook​

Send a test message from the external platform to verify everything works:

  1. Send a message from a registered Contact through the platform.
  2. Check the app status — should remain "Verified".
  3. Check Doorkeeper — a conversation should be created or continued.
tip

If messages are not arriving, check these common issues:

  • Incorrect webhook URL — Verify the app ID in the URL
  • Missing credentials — Check the credential checklist on the app card
  • Signature mismatch — Verify the signing secret/app secret matches
  • Unknown sender — Only registered Contacts are processed; check Settings > Contacts

7. Message Routing​

Inbound webhook messages are routed to:

  • Waitbox — If a running workflow is awaiting user input, the message is delivered as a reply.
  • Doorkeeper — Otherwise, the message starts or continues a Doorkeeper conversation.

Routing is automatic based on the conversation state. Waitbox replies take priority over new Doorkeeper conversations.

What's Next​

Learn More​