الـ Webhooks

الـ Webhooks بتبعت طلب HTTP POST للسيرفر بتاعك لما يحصل حدث على إيميلاتك، عشان أنظمتك تفضل متزامنة.

آخر تحديث: 2026-10-13

الأحداث#

اعمل Webhook#

في البورتال افتح الربط → Webhooks وضيف الرابط اللي هيستقبل الأحداث، واختار الحدث. استخدم نافذة Test Webhook عشان تشوف مثال للبيانات لكل حدث.

بالـ API:

curl -s -X POST https://mailhoor.com/api/webhooks \
  -H "X-Auth-APIKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Unsubscribes to CRM", "target_url": "https://yourapp.com/hooks/mailhoor", "event": "unsub"}'

الرد بيكون 201 ومعاه الـ Webhook الجديد. ولو رجع 409 يبقى نفس الـ Webhook موجود بالفعل.

استقبال الأحداث#

• الرابط لازم يكون HTTPS ويرد بـ HTTP 200 بسرعة. اعمل الشغل التقيل بعد ما ترد.
• نفس الحدث ممكن يوصل أكتر من مرة. خلّي الكود بتاعك يستحمل التكرار.
• اعتبر البيانات مدخلات غير موثوقة: راجعها قبل ما تكتبها في قاعدة البيانات.

اتأكد من التوقيع#

كل Webhook فيه هيدرين: X-MailHoor-Timestamp (ثواني Unix) وX-MailHoor-Signature (sha256= + HMAC-SHA256 للـ timestamp ونقطة والـ body زي ما وصل). هتلاقي مفتاح التوقيع في الربط → Webhooks → مفتاح التوقيع.

import hashlib, hmac, time

def verify(secret: str, timestamp: str, signature: str, raw_body: bytes) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "sha256=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

استخدم الـ body زي ما وصل بالظبط قبل ما تحوّله لـ JSON. وارفض أي طلب أقدم من 5 دقايق. ولو غيّرت المفتاح، حدّث السيرفر بتاعك على طول.

استخدامات شائعة#

• تعليم العملاء اللي ألغوا اشتراكهم في الـ CRM (unsub وcomplaint).
• تنضيف العناوين اللي رجعت من قاعدة بياناتك (bounce).
• تقييم العملاء المحتملين حسب التفاعل (open_click).