الويب هوكس

تسمح الويب هوكس لتطبيقك باستقبال إشعارات فورية عند حدوث أحداث مختلفة في Omdaa API، مثل استقبال رسالة جديدة، إرسال رسالة، أو اتصال جلسة.

إعداد عنوان Webhook

"function">curl "keyword">-X POST https://omdaa.com/api/v1/webhooks/set \
  "keyword">-H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "keyword">-H "Content"keyword">-Type: application/json" \
  "keyword">-d '{
  "webhookUrl": "https://your class="keyword">-server.com/webhook",
  "events": ["message.incoming", "message.sent", "session.connected"]
}'

أمثلة للأحداث

رسالة واردة message.incoming

{
  "event": "message.incoming",
  "data": {
    "messageId": "msg_123",
    "from": "966501234567",
    "message": "مرحبا",
    "timestamp": "2025-01-15T12:00:00Z"
  }
}

رسالة مرسلة message.sent

{
  "event": "message.sent",
  "data": {
    "messageId": "msg_123",
    "to": "966501234567",
    "status": "sent",
    "timestamp": "2025-01-15T12:00:00Z"
  }
}

اتصال جلسة session.connected

{
  "event": "session.connected",
  "data": {
    "sessionId": "sess_123",
    "phoneNumber": "966501234567",
    "connectedAt": "2025-01-15T12:00:00Z"
  }
}

التحقق من التوقيع

عند ضبط secret عبر POST /webhooks/set، يُرسل Omdaa مع كل تسليم:

X-Webhook-Signature: sha256=<hmac_hex>
X-Webhook-Timestamp (Unix seconds) لمنع إعادة التشغيل

الصيغة: HMAC_SHA256(secret, raw_request_body) حيث raw_request_body هو جسم JSON كما وصل حرفياً (UTF-8). السر يُخزَّن plaintext داخلياً لتوقيع الصادر ولا يُعاد في GET /webhooks (hasSecret: true فقط). حدث test يعمل بدون جلسة واتساب.

Node.js

const crypto = require('crypto');
function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
  const a = Buffer.from(signatureHeader || '');
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Express: app.use(express.json({ verify: (req,res,buf) => { req.rawBody = buf; } }));
// verify(req.rawBody, req.get('X-Webhook-Signature'), process.env.WEBHOOK_SECRET);

Python

import hmac, hashlib
def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    digest = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    expected = f"sha256={digest}"
    return hmac.compare_digest(signature_header or "", expected)

PHP

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
$ok = hash_equals($expected, $sig);

الحصول على إعدادات Webhook

للحصول على إعدادات Webhook الحالية:

"function">curl "keyword">-X GET "https://omdaa.com/api/v1/webhooks" \
  "keyword">-H "Authorization: Bearer YOUR_JWT_TOKEN"

اختبار Webhook

لاختبار اتصال Webhook:

"function">curl "keyword">-X GET "https://omdaa.com/api/v1/webhooks/test" \
  "keyword">-H "Authorization: Bearer YOUR_JWT_TOKEN"

إحصائيات Webhook

للحصول على إحصائيات Webhook:

"function">curl "keyword">-X GET "https://omdaa.com/api/v1/webhooks/stats" \
  "keyword">-H "Authorization: Bearer YOUR_JWT_TOKEN"

Circuit Breaker

Omdaa API يستخدم Circuit Breaker لحماية Webhook من الفشل المتكرر:

الحصول على حالة Circuit Breaker

"function">curl "keyword">-X GET "https://omdaa.com/api/v1/webhooks/circuit class="keyword">-breaker" \
  "keyword">-H "Authorization: Bearer YOUR_JWT_TOKEN"

إعادة تعيين Circuit Breaker

"function">curl "keyword">-X POST "https://omdaa.com/api/v1/webhooks/circuit class="keyword">-breaker/reset" \
  "keyword">-H "Authorization: Bearer YOUR_JWT_TOKEN"

جميع الأحداث المتاحة

message.incoming

رسالة واردة

message.sent

رسالة مرسلة

message.delivered

رسالة تم تسليمها

message.read

رسالة تم قراءتها

session.connected

جلسة متصلة

session.disconnected

جلسة منفصلة

group.created

مجموعة جديدة

group.updated

تحديث مجموعة