וובהוקים (Webhooks)

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

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

ההיפוך הקטן הזה לכאורה — מי מחכה למי — משנה הכל.

תבנית הוובהוק

שלושה שלבים:

רישום. אתה נותן לשירות כתובת URL: https://yourdomain.com/webhooks/payment-received. השירות שומר אותה.

התרחשות אירוע. משהו קורה — תשלום מושלם, משתמש נרשם, קובץ מסיים עיבוד.

מסירה. השירות מיד שולח בקשת POST עם מטען JSON לכתובת ה-URL שלך. אתה מעבד אותו ומגיב עם HTTP 200.

זהו. אין לולאות פולינג. אין בקשות מבוזבזות. אין עיכובים מלאכותיים.

למה זה חשוב

פולינג מאלץ אותך לבחור בין מהירות תגובה ויעילות. לסקר כל שנייה? תפגיז את ה-API עם בקשות שברובן לא מחזירות כלום. לסקר כל דקה? תפספס אירועים רגישים לזמן בעד 59 שניות.

וובהוקים מבטלים את ההתפשרות הזו. אירועים מגיעים ברגע שהם קורים. אתה מקבל בקשות רק כשיש משהו לעבד. השירות נושא בנטל לצפות בשינויים — לא אתה.

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

איך נראה וובהוק

מטען וובהוק טיפוסי:

{
  "event": "payment.completed",
  "timestamp": "2024-01-15T10:30:00Z",
  "id": "evt_abc123",
  "data": {
    "payment_id": "pay_xyz789",
    "amount": 49.99,
    "currency": "USD",
    "customer_id": "cust_123456"
  }
}

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

שירותים שולחים סוגי אירועים רבים לאותה כתובת URL — payment.completed, payment.failed, payment.refunded — ולכן המטפל שלך מנתב לפי סוג האירוע.

אבטחה: בעיית הוובהוק הלא חתום

הנה הסכנה: כתובת ה-URL של הוובהוק שלך היא פשוט כתובת URL. כל מי שמגלה אותה יכול לשלוח אירועים מזויפים. ללא אימות, תוקף יכול לשלוח אירוע payment.completed מזויף ולרמות את המערכת שלך לבצע הזמנה שלעולם לא שולמה.

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

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
    const expected = crypto
        .createHmac('sha256', secret)
        .update(payload)
        .digest('hex');

    return crypto.timingSafeEqual(
        Buffer.from(signature),
        Buffer.from(expected)
    );
}

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

מלכודת המהירות

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

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

התבנית: לאשר מיד, לעבד מאוחר יותר.

app.post('/webhooks/payment', async function(request, response) {
    if (!verifySignature(request)) {
        return response.status(401).send('Invalid signature');
    }

    // הכנס לתור לעיבוד ברקע
    await queue.add('process-payment-webhook', request.body);

    // הגב מיד
    response.status(200).send('OK');
});

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

בעיית הכפילויות

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

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

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

async function processWebhook(event) {
    const exists = await db.webhookEvents.findOne({ id: event.id });
    if (exists) {
        return; // כבר עובד
    }

    await handleEvent(event);
    await db.webhookEvents.insert({ id: event.id, processed_at: new Date() });
}

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

בדיקה ללא השירות

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

בזמן פיתוח, ה-localhost שלך אינו נגיש מהאינטרנט. כלים כמו ngrok פותרים זאת:

ngrok http 3000

זה יוצר כתובת URL ציבורית (כמו https://abc123.ngrok.io) שמנהרת לשרת המקומי שלך. כוון את הגדרות הוובהוק של השירות לכתובת URL זו, והוובהוקים זורמים למחשב הפיתוח שלך.

לבדיקות אוטומטיות, דמה את הוובהוק:

test('handles payment webhook', async function() {
    const payload = {
        event: 'payment.completed',
        id: 'evt_test_123',
        data: { payment_id: 'pay_test_456' }
    };

    const response = await request(app)
        .post('/webhooks/payment')
        .send(payload);

    expect(response.status).toBe(200);
});

רוב השירותים גם מספקים סימולטורי וובהוק בלוחות הבקרה שלהם — כפתורים ששולחים אירועי בדיקה לכתובת ה-URL הרשומה שלך.

היכן מופיעים וובהוקים

מעבדי תשלומים (Stripe, PayPal) מודיעים לך כשתשלומים מושלמים, נכשלים, או מוחזרים. אתה מעדכן את סטטוס ההזמנה ומבצע רכישות מיד.

מאגרי קוד (GitHub, GitLab) מודיעים לך על דחיפות, בקשות משיכה ובעיות. צינורות CI/CD מופעלים על ידי וובהוקים אלה.

שירותי תקשורת (Twilio, SendGrid) מודיעים לך על מסירת הודעות, SMS נכנס, פתיחת מיילים וקליקים.

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

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

בניית וובהוקים עבור אחרים

אם השירות שלך מציע וובהוקים:

חתום על הכל. השתמש בחתימות HMAC כדי שמקבלים יוכלו לאמת אותנטיות.

נסה שוב עם השהייה. כשמסירה נכשלת, נסה שוב לאחר מרווחים הולכים וגדלים — דקה אחת, 5 דקות, 30 דקות. תן למקבלים זמן להתאושש מבעיות זמניות.

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

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

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

וובהוקים לעומת חלופות

Server-Sent Events (SSE) שומרים על חיבורים פתוחים לעדכוני שרת-ללקוח. טוב לדפדפנים, אך דורש חיבורים מתמשכים.

WebSockets מספקים תקשורת דו-כיוונית בזמן אמת. מורכב יותר, אך מאפשר הודעות דו-כיווניות.

תורי הודעות (RabbitMQ, AWS SQS) מספקים העברת הודעות אסינכרונית אמינה. יותר תשתית, אבל יותר ערבויות.

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

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

שאלות נפוצות על וובהוקים

מה קורה אם נקודת הקצה של הוובהוק שלי מושבתת?

שירותים מנסים שוב מסירות שנכשלו עם השהייה מעריכית — בדרך כלל ניסיון חוזר לאחר דקה, אחר כך 5 דקות, אחר כך 30 דקות, ממשיכים 24–72 שעות לפני שמוותרים. עקוב אחרי נקודת הקצה שלך ולוח הבקרה של הוובהוק בשירות לכשלים. חלק מהשירותים מאפשרים לך להפעיל מחדש ידנית אירועים שפוספסו.

איך אני יודע שוובהוק הוא לגיטימי ולא ממתקיף?

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

האם אני יכול לקבל וובהוקים ב-localhost בזמן פיתוח?

לא ישירות — localhost אינו נגיש מהאינטרנט. השתמש בכלי מנהור כמו ngrok, שיוצר כתובת URL ציבורית שמעבירה בקשות לשרת המקומי שלך. כוון את הגדרות הוובהוק של השירות לכתובת ה-URL של ngrok.

מדוע אני מקבל את אותו וובהוק מספר פעמים?

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