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

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

הכותרות

webhook-id:         msg_01M03VKMCJ5H7C1E4K1EEA987B
webhook-timestamp:  1786836013
webhook-signature:  v1,atTVDyPi26ackTT4nZbdk…

HookGet חותם לפי Standard Webhooks, המפרט הפתוח, ולכן צרכן שנכתב לכל שולח תואם לא צריך שום שינוי. webhook-id הוא מזהה המסירה, webhook-timestamp הוא זמן השליחה בשניות, ו-webhook-signature נושא את החתימה עצמה, עם קידומת גרסה.

פונקציית האימות

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(secret, headers, rawBody) {
  const id = headers['webhook-id'];
  const ts = Number(headers['webhook-timestamp']);

  // Outside the window this is a replay, not a delivery.
  if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key)
    .update(`${id}.${ts}.${rawBody}`)   // the RAW bytes, never a re-serialised object
    .digest('base64');

  return String(headers['webhook-signature'] ?? '')
    .split(' ')
    .some((part) => {
      const [version, value] = part.split(',');
      const a = Buffer.from(value ?? '', 'utf8');
      const b = Buffer.from(expected, 'utf8');
      return version === 'v1' && a.length === b.length && timingSafeEqual(a, b);
    });
}

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

בשביל מה כל חלק

יש כאן שני דברים עם שם דומה, וכדאי לא לבלבל ביניהם. מתקפת שליחה חוזרת היא מישהו ששולח שוב בקשה אמיתית שהוא לכד, כדי שתטופל פעם נוספת. שליחה חוזרת (replay) של אירוע ב-HookGet היא פעולה מכוונת שלכם, והיא יוצאת עם חותמת זמן חדשה וחתימה חדשה, ולכן עוברת את האימות. חותמת הזמן חתומה, אז תוקף לא יכול לרענן אותה בלי הסוד.

החלפת סוד בלי לאבד מסירות

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

curl -X POST https://api.hookget.com/v1/endpoints/ep_…/rotate-secret \
  -H "authorization: Bearer $HOOKGET_KEY" -d '{"expiry_hours":24}'