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 > API Tokens (webhook card)

---

Registering a Webhook

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

After registration, Orki shows you the webhook secret once — save it securely. This secret (not the verify token) is the HMAC key used to sign every delivery.

Event Types

Event	Description
meta.message	A message was received from WhatsApp/Instagram
message.created	A new message was created (inbound or outbound)
chat.status_changed	A 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-Orki-Signature-256 header containing sha256=<hex_digest> of the request body. The HMAC key is the webhook secret returned once at registration — NOT the verify token (the verify token is only used in the GET verification handshake).

Always verify signatures to ensure payloads are genuinely from Orki.

Example (Node.js)

const crypto = require('crypto');

// webhookSecret = the secret shown once when you registered the webhook
function verifySignature(payload, signature, webhookSecret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', webhookSecret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// signature = req.headers['x-orki-signature-256']

note

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 up to 3 times, with a backoff of roughly 1 second, 5 seconds, then 30 seconds. 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 10 seconds, or the delivery will be marked as failed.

tip

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

---

Next Steps

• API Tokens — Create programmatic API access for external systems
• System Events — The inbound mirror of webhooks: your backend fires structured events at a chat