אימות בקשות חתומות מאקסטרה

כשאנחנו שולחים בקשה לכתובת שלכם, הכתובת הזו פתוחה לאינטרנט, ולכן כדאי לוודא שכל בקשה שמגיעה אליה באמת נשלחה מאיתנו. בשביל זה אנחנו חותמים על הבקשות שאנחנו שולחים. כרגע החתימה משמשת ב-GenieAI On Demand: כשעיבוד מסתיים, התוצאה נשלחת חתומה לכתובת שהגדרתם ב-callback_url.

יש שתי דרכים לוודא שבקשה הגיעה מאיתנו - אחת בלי שורת קוד, ואחת לפי החתימה שמצורפת לכל בקשה. שתיהן לא חובה.

הדרך הפשוטה: טוקן משלכם בכתובת

מתאימה לכלים בלי קוד, כמו Make ו-Zapier.

1. בחרו מחרוזת אקראית וארוכה משלכם, למשל k7Qp2xVb9mR4.
2. הוסיפו אותה לכתובת שאתם שולחים ב-callback_url: https://hooks.example.com/genie?token=k7Qp2xVb9mR4
3. בצד שלכם, בדקו שכל בקשה שמגיעה מכילה את הטוקן הזה, והתעלמו מכל בקשה אחרת.

אנחנו קוראים לכתובת בדיוק כפי שהיא נשלחה אלינו, כולל הפרמטרים, כך שהטוקן תמיד יגיע.

הדרך המלאה: בדיקת החתימה

כל בקשה שאנחנו שולחים כוללת כותרת בשם X-Extra-Signature-256. הערך שלה הוא חתימת HMAC-SHA256 של גוף הבקשה, בסוד החתימה של החשבון שלכם, בקידוד base64.

הסוד: מוצג באזור האישי, בעמוד API, בכרטיס "סוד חתימה". סוד אחד לחשבון, לכל השירותים שחותמים. הוא מתחיל ב-whsec_, וכל המחרוזת, כולל whsec_, היא המפתח.

כדי לבדוק בקשה:

1. קראו את גוף הבקשה כפי שהתקבל, כטקסט גולמי, לפני כל פענוח של JSON. פענוח וקידוד מחדש משנים רווחים וסדר, והחתימה כבר לא תתאים.
2. חשבו HMAC-SHA256 של הגוף הגולמי, עם הסוד כמפתח, וקודדו את התוצאה ב-base64.
3. השוו לערך שבכותרת X-Extra-Signature-256 בהשוואה בזמן קבוע (constant time), ולא בהשוואת מחרוזות רגילה.
4. אם יש התאמה - הבקשה מאיתנו. אם לא - החזירו שגיאה והתעלמו ממנה.

דוגמה ב-PHP

$secret = 'whsec_...'; // מהאזור האישי $body = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_EXTRA_SIGNATURE_256'] ?? ''; $expected = base64_encode(hash_hmac('sha256', $body, $secret, true)); if (!hash_equals($expected, $signature)) { http_response_code(401); exit; } $job = json_decode($body, true);

דוגמה ב-Node.js

const crypto = require('crypto'); // rawBody = גוף הבקשה כ-Buffer, לפני פענוח (ב-Express: express.raw({ type: 'application/json' })) function isFromExtra(rawBody, signature, secret) { const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('base64'); const a = Buffer.from(expected), b = Buffer.from(signature || ''); return a.length === b.length && crypto.timingSafeEqual(a, b); }

דוגמה ב-Python

import base64, hashlib, hmac def is_from_extra(raw_body: bytes, signature: str, secret: str) -> bool: expected = base64.b64encode(hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()).decode() return hmac.compare_digest(expected, signature or '')

החלפת הסוד

אפשר להחליף את הסוד בכל רגע, מאותו מקום שבו הוא מוצג. מהרגע שהחלפתם, בקשות חדשות ייחתמו בסוד החדש. בקשות שכבר יצאו לדרך עשויות להמשיך להגיע חתומות בסוד הקודם, ולכן כדאי לקבל את שניהם לזמן קצר.

עוד כמה דברים שכדאי לדעת

• ענו מהר. החזירו תשובה מסוג 2xx תוך 10 שניות, ועשו את העבודה הכבדה אחר כך. תשובה אחרת, או תשובה שמתעכבת, תגרום לנו לשלוח את הבקשה שוב.
• אותה בקשה עלולה להגיע פעמיים. פעלו על כל בקשה פעם אחת בלבד, לפי המזהה שבגוף הבקשה.
• החתימה לא כוללת חותמת זמן. אם חשוב לכם לחסום שליחה חוזרת של בקשה ישנה, שמרו את המזהים של מה שכבר טיפלתם בו.

לפי שירות

שאלות נפוצות

• האם חובה לאמת את הבקשות שאתם שולחים?

  לא. הבקשות מגיעות אליכם בכל מקרה, והאימות הוא הגנה שאתם מוסיפים בצד שלכם. אנחנו ממליצים עליו כשהכתובת שלכם פתוחה לאינטרנט והמערכת שלכם פועלת על סמך מה שמגיע אליה.

• חישבתי את החתימה והיא לא תואמת לכותרת. מה כדאי לבדוק?

  שלושה דברים, לפי הסדר: שחישבתם על גוף הבקשה הגולמי כפי שהתקבל, לפני פענוח ה-JSON; שהשתמשתם בסוד כולו, כולל התחילית whsec_; ושהתוצאה מקודדת ב-base64 ולא בהקסדצימלי.

• אפשר להשתמש גם בטוקן בכתובת וגם בבדיקת החתימה?

  כן. הטוקן יושב בכתובת והחתימה בכותרת, והם לא מפריעים זה לזה. אפשר להתחיל בטוקן ולהוסיף את בדיקת החתימה בהמשך.

• מה עושים אם הסוד נחשף?

  מחליפים אותו מיד, באזור האישי, באותו מקום שבו הוא מוצג. בקשות חדשות ייחתמו בסוד החדש, ולכן לזמן קצר כדאי לקבל את שני הסודות ואז להסיר את הישן.

• אפשר לבדוק את החתימה בכלים בלי קוד, כמו Make או Zapier?

  בכלים כאלה הכי פשוט להשתמש בטוקן בכתובת - הדרך הזו נועדה בדיוק להם. אם הכלי שלכם יודע לחשב HMAC-SHA256 בקידוד base64, אפשר לבדוק בו גם את החתימה.