إنتقل إلى المحتوى الرئيسي

Webhooks

Webhooks are real-time HTTP notifications sent to your server when events happen in Orki. Instead of polling for changes, your system receives instant updates whenever a message arrives, a chat status changes, or other events occur.

Path: Settings > Webhooks

Registering a Webhook​

  1. Go to Settings > Webhooks
  2. Click "Add Webhook"
  3. Enter your webhook URL (must be HTTPS)
  4. Enter a verify token (a secret string used for the verification handshake)
  5. Select the event types you want to subscribe to

Event Types​

EventDescription
meta.messageA message was received from WhatsApp/Instagram
message.createdA new message was created (inbound or outbound)
chat.status_changedA chat's status changed (active, snoozed, closed, needs attention)

Verification Handshake​

When you register a webhook, Orki sends a GET request to your URL to verify ownership:

  1. Orki sends a GET request with a hub.challenge parameter and your verify token
  2. Your server validates the verify token matches what you configured
  3. Your server responds with the hub.challenge value in the response body

This confirms that you own the endpoint and are ready to receive events.

HMAC-SHA256 Signature Verification​

Every webhook payload includes an X-Hub-Signature-256 header containing sha256=<hex_digest> of the request body, using your verify token as the HMAC key.

Always verify signatures to ensure payloads are genuinely from Orki.

Example (Node.js)​

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
ملاحظة

Use timingSafeEqual (or equivalent in your language) to prevent timing attacks when comparing signatures.

Delivery Logs​

View the delivery history for each webhook to monitor and debug your integration.

What You Can See​

  • Event type — which event triggered the delivery
  • Response status code — what your server responded with
  • Response time — how long your server took to respond
  • Timestamp — when the delivery was attempted
  • Error details — shown for failed deliveries

Filtering​

Filter delivery logs by:

  • Event type
  • Success or failure
  • Date range

Retry Behavior​

Failed deliveries are automatically retried. Orki tracks the failure count for each webhook — webhooks with too many consecutive failures display a warning in the dashboard.

Test Events​

Before going live, use the test event feature to verify your endpoint is working correctly. This sends a sample payload to your webhook URL so you can confirm everything is wired up properly.

warning

Make sure your endpoint responds with a 2xx status code within 5 seconds, or the delivery will be marked as failed.

تلميح

Use the delivery logs to debug integration issues — they show exactly what was sent and what your server responded.

Next Steps​