דלגו לתוכן

Webhooks

RolChat מוסר אירועים למערכות שלכם כבקשות HTTP POST חתומות. הדף הזה מתאר webhooks של תוספים; webhooks שנשלחים מכלל אוטומציה שונים בניסיונות החוזרים, בזמן ההמתנה ובהחלפת הסוד, ראו Webhooks של האוטומציה. אותם כללים חלים גם בכיוון ההפוך, כשהמערכת שלכם, תוסף או ספק שולחים ל-RolChat. אמתו כל משלוח לפי הסדר שלהלן לפני שאתם פועלים על פיו.

איך נראה משלוח

Section titled “איך נראה משלוח”
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: RolChat-Webhook/1.0
X-RolChat-Timestamp: 1713615825
X-RolChat-Signature: sha256=a1b2c3…
X-RolChat-Nonce: nonce_01HKQN9…
X-RolChat-Event-Id: evt_01HKQN9…


{ "id": "evt_01HKQN9…", "type": "conversation.created", "occurred_at": "…", "data": { … } }
כותרת משמעות
X-RolChat-Timestamp שניות Unix ברגע השליחה. חלק מההודעה החתומה.
X-RolChat-Signature sha256=<hex>. הקידומת מציינת את האלגוריתם כדי שאפשר יהיה לשנות אותו בעתיד.
X-RolChat-Nonce ULID ייחודי לבקשת HTTP זו. ניסיון חוזר מקבל nonce חדש.
X-RolChat-Event-Id המזהה של האירוע עצמו. יציב בין ניסיונות חוזרים; השתמשו בו להסרת כפילויות.

משלוחים יוצאים נשלחים לנקודות קצה HTTPS בלבד. כתובת HTTP נדחית בעת יצירת המינוי.

החתימה

Section titled “החתימה”

ההודעה החתומה היא חותמת הזמן, נקודה מילולית, וגוף הבקשה הגולמי, בית אחר בית:

canonical = "<timestamp>.<body>"
signature = hex( HMAC-SHA256( secret, canonical ) )

חתמו על הבתים שקיבלתם, לא על עותק שעבר סריאליזציה מחדש מה-JSON המפוענח. שינויים ברווחים או בסדר המפתחות שוברים את החתימה. SHA-256 הוא האלגוריתם היחיד שמתקבל.

אימות משלוח

Section titled “אימות משלוח”

בצעו את חמש הבדיקות האלה לפי הסדר. דוגמאות ב-Python, ‏Node.js, ‏Go, ‏Ruby ו-PHP נמצאות בעמוד דוגמאות האימות.

  1. טריות. דחו אם |now − X-RolChat-Timestamp| > 300 שניות (400). חמש דקות סובלות סטיית שעון והופכות בקשה שנלכדה לחסרת ערך אחרי כן. שמרו על השרת שלכם מסונכרן ב-NTP.
  2. חתימה. חשבו את הערך הצפוי והשוו בהשוואה בזמן קבוע (hmac.compare_digest, crypto.timingSafeEqual, hash_equals). דחו עם 401 באי-התאמה. השוואת מחרוזות רגילה מדליפה תזמון ואינה מקובלת.
  3. Nonce. שמרו את X-RolChat-Nonce עם TTL של 10 דקות בעזרת פעולה אטומית של “קבע אם לא קיים” (SET NX EX 600). אם הוא כבר קיים, דחו עם 409: הבקשה היא שידור חוזר. אם מאגר ה-nonce שלכם לא זמין, היכשלו באופן סגור עם 503 כדי ש-RolChat ינסה שוב; לעולם אל תיפלו ל“קבלה”.
  4. פענחו את הגוף רק עכשיו.
  5. הסירו כפילויות לפי מזהה האירוע. ניסיונות חוזרים נושאים nonce חדש אבל את אותו X-RolChat-Event-Id. אם עיבדתם את המזהה הזה בשבעת הימים האחרונים, ענו 200 בלי לעבד שוב.

ענו 2xx ברגע שהמשלוח התקבל בבטחה; בצעו את העבודה באופן אסינכרוני. RolChat ממתין לתגובה 15 שניות.

סודות

Section titled “סודות”
  • סוד webhook הוא 64 בתים אקראיים בקידוד base64url (כ-86 תווים). הוא נוצר כשהמינוי או התוסף נוצרים ומוצג פעם אחת.
  • שמרו אותו בכספת או בסביבה שלכם; RolChat שומר רק עותק מוצפן.
  • מומלץ להחליף אותו אחרי 90 יום; המוצר מציג תזכורת אבל לעולם אינו משבית מינוי בגלל אי-החלפה.
  • ההחלפה משתמשת בחלון חפיפה: אחרי POST /api/v1/plugins/{id}/webhook-secret/rotate גם הסוד הישן וגם החדש מאמתים במשך שבעה ימים, משלוחים חדשים נחתמים בחדש, והישן נמחק אחרי החלון. שום דבר לא נשבר ברגע ההחלפה.
  • אם סוד דלף, POST /api/v1/plugins/{id}/webhook-secret/revoke מבטל אותו מיד, מנפיק חדש, שולח אימייל למנהלי החשבון וכותב רשומה ביומן הביקורת.

ניסיונות חוזרים והודעות מתות

Section titled “ניסיונות חוזרים והודעות מתות”

תגובה שאינה 2xx או כשל רשת מתזמנים ניסיון חוזר:

ניסיון השהיה אחרי הקודם
1 מיד
2 15 שניות
3 דקה
4 5 דקות
5 30 דקות
6 שעתיים
7 8 שעות
8 24 שעות

על 408, 429, 5xx ושגיאות רשת מנסים שוב. על 400, 401, 403, 404 ו-410 לא: המשלוח עובר ישר לתור ההודעות המתות, כי ניסיון חוזר על חתימה שנדחתה או על נקודת קצה חסרה לא יכול לעזור. אחרי שמונה ניסיונות כושלים המשלוח עובר גם הוא להודעות מתות.

הודעות מתות נשמרות 30 יום וגלויות בהגדרות ← תוספים ← {plugin} ← יומן Webhook ← DLQ, שם מנהל מערכת יכול להריץ אחת מחדש (POST /api/v1/plugins/{id}/webhook-dlq/{entry_id}/replay).

מגבלות

Section titled “מגבלות”
  • גוף יוצא: 1 MB כברירת מחדל (ניתן להגדרה לכל תוסף). גוף נכנס ל-RolChat: ‏5 MB. גדול יותר מקבל 413.
  • תוסף יכול להצהיר על allowed_source_ips; RolChat מחיל את רשימת ההיתרים הזו לפני האימות.
  • אפשר להסתמך על ה-user agent ‏RolChat-Webhook/1.0 כבדיקת שפיות נוספת. זה אינו אמצעי אבטחה.

Webhooks נכנסים ל-RolChat

Section titled “Webhooks נכנסים ל-RolChat”

ספקים שולחים ל-RolChat בכתובת /api/v1/webhooks/{category}/{adapter} עם שיטות החתימה שלהם (Twilio, Telnyx, Bandwidth, Meta עבור WhatsApp, Stripe). כל מתאם מאמת את חתימת הספק שלו, מנרמל את המטען ומפרסם אותו מחדש באפיק האירועים הפנימי עם חתימת RolChat. המערכת שלכם יכולה לשלוח ל-RolChat עם אותן כותרות X-RolChat-* שתוארו למעלה, חתומות בסוד של התוסף שנקודת הקצה שייכת לו.

Webhooks של האוטומציה

Section titled “Webhooks של האוטומציה”

לפעולה שליחת בקשת HTTP של מודול האוטומציה יש כללי משלוח משלה:

  • סוד אחד לכל חשבון. אפשר להציג או להחליף אותו במסך האוטומציה (בעלים ומנהל מערכת). ההחלפה נכנסת לתוקף מיד: אין חלון חפיפה, הסוד הישן מפסיק לעבור אימות מיד, ולכן עדכנו קודם את המקבל שלכם או קבלו פער קצר.
  • זמן המתנה: RolChat ממתין לתשובה 10 שניות.
  • ניסיונות חוזרים: עד 6 ניסיונות בסך הכול. ההפסקה לפני ניסיון 2 היא 30 שניות, ואחר כך כ-2 דקות, 8 דקות, 32 דקות ושעתיים ו-8 דקות, כל אחת משתנה בעד 20 %. הפסקה בודדת אינה עולה על 6 שעות.
  • מה נשלח שוב: שגיאות רשת, פסקי זמן, 5xx, 408, 425 ו-429. תשובות 4xx אחרות, כתובת חסומה או גוף גדול מדי אינם נשלחים שוב: המשלוח עובר ישר לתור המכתבים המתים, כמו אחרי הניסיון האחרון שנכשל.
  • כותרות: X-RolChat-Signature, X-RolChat-Signature-V2, X-RolChat-Timestamp, X-RolChat-Delivery-Id, X-RolChat-Attempt.

בדיקת המקבל שלכם

Section titled “בדיקת המקבל שלכם”

POST /api/v1/webhooks/test-signature שולח אירוע סינתטי חתום לנקודת הקצה של התוסף הקורא, כדי שתוכלו לאמת את המימוש שלכם מקצה לקצה לפני שמגיעה תעבורה אמיתית.

טעויות נפוצות

Section titled “טעויות נפוצות”
  • אימות מול JSON שפוענח וקודד מחדש במקום מול הבתים הגולמיים.
  • שימוש ב-== להשוואת חתימות.
  • הסרת כפילויות לפי nonce (לכל ניסיון חוזר יש nonce חדש) במקום לפי מזהה האירוע.
  • שעון שסוטה ביותר מחמש דקות.
  • ביצוע עבודה איטית לפני המענה, ואז חריגה מזמן קצוב של 15 שניות וקבלת אותו אירוע שוב.