הגדרת Webhooks

Published: 16 ביולי 2026 · Last updated: 21 ביולי 2026 · By Marcus Biel

In brief

למדו כיצד להגדיר נקודות קצה ל-Webhooks ב-Maildroppa, לבחור אירועים, לאמת חתימות, לבדוק משלוחים, לעקוב אחר ניסיונות חוזרים ולשדר אירועים מחדש.

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

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

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

Webhooks: דף Webhooks מלא

כיצד Webhooks ברמת החשבון פועלים

Webhook ברמת החשבון פועל בתהליך הבא:

אירוע מתרחש ב-Maildroppa, למשל יצירת נרשם.
Maildroppa מאתרת כל נקודת קצה פעילה שמנויה לאותו אירוע.
Maildroppa יוצרת מסירה אחת עבור כל נקודת קצה מתאימה.
מטען ה-JSON נחתם באמצעות סוד החתימה של ה-Webhook של החשבון.
Maildroppa שולחת בקשת HTTPS מסוג POST לכתובת נקודת הקצה השמורה.
נקודת הקצה שלכם מאמתת את החתימה, שומרת או מעבדת את האירוע ומחזירה תגובת HTTP.
Maildroppa מתעדת את התוצאה בהיסטוריית המסירות ומנסה שוב באופן אוטומטי במקרה של כשלים זמניים.

אם כמה נקודות קצה מנויוֹת לאותו אירוע, כל נקודת קצה מקבלת מסירה משלה. לאירוע העסקי יש אותו Event ID עבור כולן, בעוד שלכל מסירה יש Delivery ID משלה.

Webhooks ברמת החשבון שונים משלב “Send a webhook” בתוך Automation. Webhooks ברמת החשבון מאזינים לאירועי חשבון נבחרים ברחבי Maildroppa. Webhook של Automation נשלח רק כאשר נרשם מגיע לשלב המסוים הזה. שניהם משתמשים בסוד החתימה של ה-Webhook של החשבון, ולכן החלפת הסוד משפיעה על כל מקבל Webhook יוצא שמאמת חתימות של Maildroppa.

פתיחת דף ה-Webhooks

פתחו את “Settings”, הרחיבו את “Developers” ובחרו ב-“Webhooks”.

הדף כולל שלושה אזורים עיקריים:

סוד חתימה
נקודות קצה
היסטוריית מסירות עבור נקודת הקצה שנבחרה

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

לפני יצירת נקודת קצה

הכינו מקבל בשרת שלכם לפני הגדרת Maildroppa. המקבל צריך:

להיות זמין דרך כתובת HTTPS ציבורית.
לקבל בקשות POST עם גוף application/json.
לשמור את גוף הבקשה הגולמי עד לאימות חתימת Maildroppa.
להחזיר סטטוס 2xx רק לאחר שהאירוע התקבל באופן בטוח.
לעבד מסירות חוזרות באופן אידמפוטנטי באמצעות Event ID.
להגיב במהירות במקום לבצע עבודה איטית במהלך הבקשה.

דפוס אמין הוא לאמת את הבקשה, לשמור את Event ID ואת המטען בתור עמיד או במסד נתונים, להחזיר 200 או 204, ולעבד את הפעולה העסקית לאחר מכן.

אל תחשפו מחשב פיתוח, כתובת רשת מקומית או סקריפט לא מוגן כמקבל Webhook בייצור. Maildroppa מקבלת רק יעדי HTTPS ציבוריים ובודקת את היעד שוב בעת שליחת המסירה.

שלב 1: יצירת סוד החתימה

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

בחלק העליון של הדף, חלונית סוד החתימה מציגה אחד מהמצבים הבאים:

Missing — עדיין לא קיים סוד חתימה.
Ready — סוד חתימה מוגדר.
Loading — Maildroppa מאחזרת את המצב הנוכחי.

לחצו על “Generate secret” כאשר המצב הוא Missing.

Maildroppa מציגה את הסוד החדש מיד. הוא מתחיל ב-whsec_. לחצו על “Copy” ושמרו אותו במנהל הסודות או בתצורת סביבה מוגנת שבה משתמש המקבל שלכם.

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

Webhooks: סוד חתימה חדש

אם איבדתם את הסוד

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

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

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

התייחסו לסוד כמו לסיסמה

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

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

אימות חתימת Webhook

כל בקשה כוללת את כותרות Maildroppa הבאות:

X-Maildroppa-Event-Id — מזהה את האירוע העסקי.
X-Maildroppa-Delivery-Id — מזהה את המסירה המסוימת הזו.
X-Maildroppa-Timestamp — זמן החתימה בשניות Unix.
X-Maildroppa-Signature — חתימת HMAC עם גרסה.

Maildroppa שולחת גם:

Content-Type: application/json
User-Agent: Maildroppa-Webhooks/1.0

לחתימה יש את הפורמט הבא:

v1=<lowercase hexadecimal HMAC>

Maildroppa יוצרת אותה באמצעות HMAC-SHA256. התוכן החתום הוא חותמת הזמן, אחריה נקודה, ואחריה גוף בקשת ה-JSON הגולמי המדויק:

<timestamp>.<raw request body>

השתמשו בסוד החתימה כמפתח ה-HMAC.

הדוגמה הבאה ב-Node.js מציגה את שלב האימות החיוני. rawBody חייב להיות הבייטים המקוריים של הבקשה, ולא JSON שכבר נותח וסודר מחדש.

import crypto from 'node:crypto';

export function verifyMaildroppaWebhook({ rawBody, timestamp, signature, signingSecret }) {
  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`, 'utf8'), rawBody]);

  const expectedSignature = `v1=${crypto
    .createHmac('sha256', signingSecret)
    .update(signedPayload)
    .digest('hex')}`;

  const received = Buffer.from(signature, 'utf8');
  const expected = Buffer.from(expectedSignature, 'utf8');

  return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

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

נתחו ועבדו את ה-JSON רק לאחר ששתי הבדיקות עברו בהצלחה.

סיבות נפוצות לשגיאות חתימה

חתימה נכשלת בדרך כלל מאחת הסיבות הבאות:

המקבל משתמש בסוד ישן לאחר החלפה.
Middleware ניתח או שינה את ה-JSON לפני חישוב החתימה.
המקבל חותם רק על הגוף ומשמיט את <timestamp>..
חותמת הזמן מטופלת כתאריך מעוצב במקום כערך הכותרת המדויק.
הקידומת v1= מושמטת מההשוואה.
ה-HMAC המחושב מקודד באופן שונה במקום בהקסדצימלי באותיות קטנות.

תעדו את Event ID ואת Delivery ID כאשר האימות נכשל, אך לעולם אל תתעדו את סוד החתימה או ערכי כותרות מותאמות אישית רגישים.

שלב 2: הוספת נקודת קצה

לחצו על “Add endpoint” באזור Endpoints.

העורך כולל ארבעה חלקים:

כתובת נקודת קצה
אירועים
כותרות מותאמות אישית
מצב פעיל

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

Webhooks: חלונית הוספת נקודת קצה

הגדרת כתובת נקודת הקצה

הזינו את הכתובת הציבורית המלאה שאמורה לקבל בקשות מ-Maildroppa, לדוגמה:

https://integrations.example.com/webhooks/maildroppa

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

עליה להשתמש ב-https://.
עליה להכיל hostname ציבורי תקף.
אורכה יכול להיות עד 2,048 תווים.
היא אינה יכולה להכיל משתני תבנית עם { או }.
היא אינה יכולה להכיל שם משתמש או סיסמה לפני ה-hostname.
היא אינה יכולה להכיל מקטע URL שמתחיל ב-#.
עליה להשתמש ביציאת HTTPS הסטנדרטית 443.
היא אינה יכולה להשתמש ב-localhost, בכתובת IP גולמית או ב-hostname שנפתר לרשת פרטית או שמורה חסומה.

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

Maildroppa אינה עוקבת אחר הפניות. שמרו את יעד ה-HTTPS הסופי במקום כתובת שמחזירה 301, 302, 307 או 308.

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

בחירת אירועים

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

הדף מציע את אפשרויות האירועים הבאות:

Subscriber Created — `subscriber.created`

נשלח כאשר נרשם נוצר בחשבון Maildroppa.

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

אל תפרשו אירוע זה כהוכחה שכל הרשמה השלימה Double Opt-in. סטטוס הנרשם במטען מתאר את המצב הנוכחי.

Subscriber Updated — `subscriber.updated`

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

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

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

Subscriber Unsubscribed — `subscriber.unsubscribed`

נשלח כאשר הנרשם עובר למצב unsubscribed באמצעות פעולת ביטול מינוי.

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

Tag Added — `subscriber.tag_added`

נשלח כאשר תגית מוקצית לנרשם.

המטען מכיל את הנרשם ואת התגית המעורבים בשינוי המסוים הזה.

Tag Removed — `subscriber.tag_removed`

נשלח כאשר תגית מוסרת מנרשם.

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

Form Submitted — `form.submitted`

נשלח כאשר מבקר שולח טופס הרשמה של Maildroppa.

התייחסו לכך כאות לשליחת טופס, ולא כאישור שה-Double Opt-in הושלם. כל תהליך שדורש מינוי מאושר חייב להמשיך לכבד את הסטטוס הנוכחי של הנרשם ואת תהליך האישור.

השתמשו בנקודות קצה נפרדות כאשר האחריות שונה

ניתן לשלוח אירועים שונים למערכות שונות. לדוגמה:

שלחו אירועי נרשמים ותגיות ל-CRM.
שלחו אירועי ביטול מינוי לשירות דיכוי.
שלחו אירועי שליחת טופס לצינור ניתוח נתונים.

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

הוספת כותרות מותאמות אישית

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

לחצו על “Add header”, ולאחר מכן הזינו את Header name ואת Header value. דוגמאות מתאימות כוללות:

Authorization: Bearer your-token

X-Integration-Key: your-secret-key

ניתן להוסיף עד 20 כותרות מותאמות אישית.

שמות כותרות:

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

ערכי כותרות:

נדרשים.
יכולים להכיל עד 2,000 תווים.
אינם יכולים להכיל מעברי שורה.

השמות הבאים שמורים ולא ניתן להחליפם באמצעות כותרת מותאמת אישית:

Content-Type
Content-Length
Host
User-Agent
כל שם שמתחיל ב-X-Maildroppa-

כך נמנע מערך מותאם אישית להחליף את כותרות המסירה והחתימה של Maildroppa.

כיצד סודות בכותרות נשמרים

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

כאשר עורכים את נקודת הקצה מאוחר יותר, שדה הערך מציג “Stored value kept”. השאירו אותו ריק כאשר הסוד הקיים צריך להישאר ללא שינוי. הזינו ערך חדש כדי להחליף אותו.

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

הסרת שורת כותרת מסירה את הכותרת ממסירות עתידיות לאחר שמירת נקודת הקצה.

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

הגדרת נקודת הקצה כפעילה או לא פעילה

השאירו את “Active” מסומן כאשר נקודת הקצה מוכנה לקבל אירועים מיד.

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

נקודת קצה לא פעילה:

אינה מקבלת אירועים חדשים שמתרחשים.
אינה יכולה לשלוח Test webhook.
נשארת גלויה וניתנת לעריכה.
שומרת את היסטוריית המסירות הקיימת שלה.

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

לחצו על “Save” כאשר הכתובת, בחירת האירועים, הכותרות והמצב נכונים.

הבנת רשימת נקודות הקצה

כל שורת נקודת קצה מציגה:

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

הפעולות הזמינות הן:

On/Off — הפעלה או השבתה של נקודת הקצה.
Test — שליחת בקשת בדיקה מיידית אחת לנקודת קצה פעילה.
Edit — שינוי הכתובת, האירועים, הכותרות או המצב הפעיל.
Delete — הסרה לצמיתות של תצורת נקודת הקצה לאחר אישור.

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

Webhooks: שורת נקודת קצה פעילה

כיצד שינויים שנשמרו משפיעים על מסירות קיימות

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

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

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

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

בדיקת נקודת קצה

לחצו על “Test” בנקודת קצה פעילה לאחר שהמקבל וסוד החתימה מוכנים.

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

מטען הבדיקה משתמש בסוג האירוע webhook.test ומגדיר את livemode כ-false:

{
  "id": "evt_test_example",
  "type": "webhook.test",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": false,
  "data": {
    "message": "This is a test webhook from Maildroppa."
  }
}

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

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

לאחר שהבקשה מסתיימת, חלונית התוצאה מציגה:

הצלחת הבדיקה או כישלון הבדיקה
Event ID
סטטוס HTTP, כאשר התקבלה תגובה
משך זמן
Delivery ID
מידע על שגיאה, כאשר זמין
קטע מתוך התגובה, כאשר המקבל החזיר גוף

הבדיקה מופיעה גם בהיסטוריית המסירות עם תגית Test. השתמשו במסנן “Test” כדי להציג רק בקשות בדיקה.

Webhooks: מסירת בדיקה מוצלחת

הבנת מטען הייצור

אירועי חשבון בייצור משתמשים במעטפת JSON משותפת:

{
  "id": "evt_example",
  "type": "subscriber.created",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {}
}

המאפיינים ברמה העליונה משמעותם:

id — ה-Event ID. תואם ל-X-Maildroppa-Event-Id.
type — מפתח האירוע שנבחר בעורך נקודת הקצה.
schema_version — גרסת סכימת המטען. השתמשו בה בעת ההחלטה כיצד לנתח את האירוע.
created_at — הזמן שבו מטען האירוע נוצר, ב-UTC.
livemode — true עבור אירועי ייצור ו-false עבור אירועי בדיקה.
data — התוכן הספציפי לאירוע.

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

מטען אירועי נרשם

אירועי נרשם מכילים את הייצוג הנוכחי של הנרשם בתוך data.subscriber:

{
  "id": "evt_example",
  "type": "subscriber.updated",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [
        {
          "id": "b6594e58-0c4b-4138-9ad8-fc4747e076eb",
          "personalization_tag_name": "company",
          "value": "Example Ltd."
        }
      ],
      "tags": [
        {
          "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
          "name": "Customers"
        }
      ]
    }
  }
}

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

מטען אירועי תגית

אירועי תגית מכילים גם את הנרשם וגם את התגית שגרמה לאירוע:

{
  "id": "evt_example",
  "type": "subscriber.tag_added",
  "schema_version": "1",
  "created_at": "2026-07-16T10:30:00Z",
  "livemode": true,
  "data": {
    "subscriber": {
      "id": "7f49d0e9-77d6-4c24-8b90-12c9d53d82cc",
      "email": "alex@example.com",
      "first_name": "Alex",
      "status": "active",
      "registered_at": "2026-07-15T08:15:00Z",
      "fields": [],
      "tags": []
    },
    "tag": {
      "id": "c69af5de-39d3-42a4-8f55-ddf86d10a51c",
      "name": "Customers"
    }
  }
}

ב-subscriber.tag_removed, data.tag עדיין מזהה את התגית שהוסרה, אף שמערך tags הנוכחי של הנרשם כבר אינו מכיל אותה.

Event IDs, Delivery IDs ואידמפוטנטיות

ל-Event ID ול-Delivery ID יש מטרות שונות.

Event ID

ה-Event ID מזהה את האירוע העסקי. הוא מופיע ב:

מאפיין id ברמה העליונה של המטען.
כותרת הבקשה X-Maildroppa-Event-Id.
היסטוריית המסירות.

אותו אירוע יכול להישלח לכמה נקודות קצה מנויוֹת. מסירות אלה חולקות את אותו Event ID.

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

Delivery ID

ה-Delivery ID מזהה רשומת מסירה אחת. הוא מופיע ב:

כותרת הבקשה X-Maildroppa-Delivery-Id.
היסטוריית המסירות.

לכל מסירת נקודת קצה יש Delivery ID משלה. הפעלה ידנית מחדש יוצרת Delivery ID חדש תוך שמירה על Event ID המקורי.

השתמשו ב-Delivery ID למעקב טכני ולתמיכה. השתמשו ב-Event ID למניעת כפילויות ברמה העסקית.

החזרת תגובת HTTP נכונה

Maildroppa מסווגת תגובות כך:

כל תגובת 2xx מסמנת את המסירה כהצלחה.
תגובות 408 Request Timeout, 429 Too Many Requests ו-5xx הן כשלים זמניים וניתן לנסות שוב.
כשלים ברשת שעשויים להיות זמניים נשלחים לניסיון חוזר.
הפניות ותגובות 3xx אחרות אינן נעקבות ונחשבות לכשלים סופיים.
תגובות 4xx אחרות נחשבות לכשלים סופיים ואינן נשלחות לניסיון חוזר.

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

אל תחזירו הפניה לכתובת Webhook אחרת. הגדירו במקום זאת את הכתובת הסופית ב-Maildroppa.

לוח זמנים לניסיונות חוזרים אוטומטיים

מסירות ייצור יכולות לבצע עד שבעה ניסיונות HTTP.

לאחר כשל שניתן לנסות שוב, Maildroppa מתזמנת את הניסיון הבא בהשהיות הבאות:

לאחר ניסיון 1: דקה אחת
לאחר ניסיון 2: 5 דקות
לאחר ניסיון 3: 30 דקות
לאחר ניסיון 4: שעתיים
לאחר ניסיון 5: 12 שעות
לאחר ניסיון 6: 24 שעות

אם ניסיון 7 עדיין מקבל כשל שניתן לנסות שוב, המסירה הופכת ל-Dead ולא מתוזמן ניסיון אוטומטי נוסף.

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

תקנו בעיית מקבל זמנית לפני מועד “Next retry” המוצג, כאשר הדבר אפשרי. אם הניסיונות האוטומטיים הסתיימו, השתמשו ב-Replay לאחר שהמקבל חזר להיות תקין.

הבנת היסטוריית המסירות

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

השתמשו במסננים הבאים:

All — מציג מסירות ייצור ובדיקה.
Production — מציג רק מסירות של אירועים חיים.
Test — מציג רק בדיקות ידניות.

לחצו על “Refresh” כדי לאחזר את המצב העדכני. אין צורך להשאיר את ההיסטוריה פתוחה בזמן ש-Maildroppa שולחת או מנסה שוב מסירה.

הדף מציג את 50 המסירות התואמות האחרונות עבור המסנן שנבחר.

Webhooks: מסנני היסטוריית מסירות

עמודות מסירה

כל שורה מכילה:

Created — מועד יצירת רשומת המסירה.
State — Pending, Success, Failed או Dead.
HTTP — סטטוס התגובה, מספר הניסיונות, משך הזמן ומועד הניסיון הבא כאשר רלוונטי.
Subscriber — כתובת הדוא״ל של הנרשם כאשר האירוע קשור לנרשם.
Delivery — סוג האירוע, Event ID ו-Delivery ID.
Actions — Replay כאשר המסירה זכאית לכך.

אם לא בוצעה בקשת HTTP, עמודת HTTP מציגה “No HTTP attempt”. מצב זה יכול להתרחש כאשר Maildroppa דוחה את הבקשה לפני השליחה, למשל כאשר סוד החתימה חסר או שלא ניתן עוד להשתמש ביעד השמור באופן בטוח.

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

מצבי מסירה

Pending פירושו שהמסירה ממתינה לניסיון הראשון או לניסיון חוזר מתוזמן. “Next retry” מופיע כאשר תוזמן ניסיון נוסף.

Success פירושו שהמקבל החזיר תגובת 2xx. אין צורך בניסיון אוטומטי נוסף.

Failed פירושו שהמסירה הסתיימה בבעיה שאינה ניתנת לניסיון חוזר, נדחתה לפני ניסיון HTTP או נעצרה לפני שניתן היה לשלוח אותה.

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

שמירת היסטוריה

רשומות מסירה נשמרות לזמן מוגבל:

מסירות ייצור מוצלחות: 30 יום
מסירות ייצור שנכשלו: 90 יום
מסירות ייצור במצב Dead: 90 יום
מסירות בדיקה: 30 יום

שמרו יומני אינטגרציה משלכם כאשר אתם זקוקים להיסטוריית ביקורת ארוכה יותר. שמרו Event IDs ו-Delivery IDs, אך הימנעו משמירת סודות ללא צורך.

הפעלה מחדש של מסירה

לחצו על “Replay” כאשר יש לנסות שוב מסירת ייצור שהושלמה.

Replay זמין למסירות ייצור במצב Success, Failed או Dead. הוא אינו זמין כאשר מסירה נמצאת במצב Pending, ולא ניתן להפעיל מחדש מסירות בדיקה.

הפעלה מחדש:

יוצרת מסירה חדשה במצב Pending.
יוצרת Delivery ID חדש.
שומרת על Event ID המקורי.
שומרת על סוג האירוע המקורי ועל מטען ה-JSON המקורי.
משתמשת בכתובת היעד המקורית השמורה ובתמונת מצב הכותרות המותאמות אישית.
משתמשת בסוד החתימה הנוכחי כאשר הבקשה החדשה מוכנה.

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

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

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

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

עריכת נקודת קצה

לחצו על “Edit” כדי לשנות את הכתובת, בחירת האירועים, הכותרות המותאמות אישית או המצב הפעיל.

לפני השמירה:

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

זכרו שמסירות שבתור שומרות את כתובת ה-URL ואת תמונת מצב הכותרות המותאמות אישית הקיימות שלהן. בדקו את התצורה החדשה עבור מסירות עתידיות במקום להניח שהיא משנה בקשה ישנה שבתור.

השבתת נקודת קצה

השתמשו במתג On/Off כאשר ברצונכם להשהות אינטגרציה בלי למחוק את התצורה וההיסטוריה שלה.

כאשר נקודת קצה מועברת למצב Off:

אירועים חדשים כבר אינם נכנסים לתור עבורה.
מסירות Pending שעדיין לא נתפסו לשליחה מסומנות כ-Failed.
Test מושבת.
נקודת הקצה נשארת זמינה לעריכה ולהפעלה מאוחרת יותר.

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

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

מחיקת נקודת קצה

לחצו על “Delete” ואשרו את האזהרה כאשר נקודת הקצה אינה אמורה להתקיים עוד.

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

Delete אינו דרך להשהיה זמנית. השתמשו במתג On/Off כאשר ייתכן שתצטרכו שוב את התצורה או את ההיסטוריה הגלויה שלה.

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

פתרון בעיות

לא ניתן לשמור את נקודת הקצה

בדקו ש:

הכתובת מתחילה ב-https://.
הכתובת משתמשת ב-hostname ציבורי וביציאה 443.
הכתובת אינה מכילה משתנים, פרטי התחברות או מקטע.
נבחר לפחות אירוע אחד.
לכל Custom header יש שם ייחודי וערך.
לא נעשה שימוש בכותרות Maildroppa ובכותרות HTTP שמורות כשמות מותאמים אישית.

Test מושבת

Test זמין רק עבור נקודת קצה פעילה. הפעילו את נקודת הקצה או ערכו אותה ובחרו ב-“Active”, ולאחר מכן שמרו לפני הבדיקה.

Test מציג שאין ניסיון HTTP

צרו סוד חתימה אם המצב הוא Missing. בדקו גם אם hostname היעד ציבורי ועדיין נפתר כראוי.

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

המקבל מחזיר `401` או `403`

בדקו את שם ה-Custom header ואת פרטי ההתחברות השמורים. ערכו את נקודת הקצה והזינו את הערך שוב אם הוא השתנה.

ודאו גם שהמקבל אינו מבלבל בין פרטי ההתחברות ל-API שלו לבין חתימת Maildroppa. כותרת הרשאה מותאמת אישית ו-X-Maildroppa-Signature משרתות מטרות שונות וניתן לבדוק אותן בנפרד.

המקבל מחזיר הפניה

Maildroppa אינה עוקבת אחר הפניות. החליפו את כתובת נקודת הקצה בכתובת HTTPS הציבורית הסופית ובדקו שוב.

החתימה אינה תואמת

ודאו שהמקבל:

משתמש בסוד החתימה הנוכחי.
משתמש בערך המדויק של X-Maildroppa-Timestamp.
חותם על <timestamp>.<raw request body>.
משתמש ב-HMAC-SHA256 ובפלט הקסדצימלי באותיות קטנות.
משווה את הערך המלא כולל v1=.
מבצע את ההשוואה לפני שניתוח JSON משנה את הגוף.

אותו אירוע מגיע יותר מפעם אחת

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

השתמשו ב-Event ID כמפתח אידמפוטנטיות. החזירו תגובת 2xx כאשר Event ID שכבר עובד מתקבל שוב ואין צורך בפעולה נוספת.

מסירה נמצאת במצב Pending

בדקו את “Next retry” בעמודת HTTP. 408, 429, 5xx שניתנים לניסיון חוזר או כשל רשת זמני יישארו במצב Pending עד לניסיון המתוזמן הבא.

לחצו על “Refresh” לאחר מועד הניסיון כדי לטעון את המצב העדכני.

מסירה נמצאת במצב Dead

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

רשימת בדיקה מומלצת לייצור

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

המקבל משתמש בכתובת HTTPS ציבורית יציבה עם אישור תקף.
סוד החתימה נשמר מחוץ לקוד המקור.
החתימה נבדקת מול הגוף הגולמי שלא השתנה.
חותמות זמן ישנות נדחות בהתאם לסבילות מתועדת.
המקבל שומר Event IDs ומונע כפילויות.
המקבל מתעד Event IDs ו-Delivery IDs לצורך מעקב.
עיבוד איטי מתבצע לאחר שהאירוע התקבל באופן עמיד.
תגובת 2xx מוחזרת רק עבור אירועים שהתקבלו.
פרטי התחברות מותאמים אישית נשמרים בכותרות ולא בכתובת ה-URL.
נבחרים רק סוגי האירועים הנדרשים.
Test webhook מצליח ומופיע כראוי בהיסטוריית המסירות.
ניטור מתריע כאשר מסירות ייצור מתחילות להחזיר שגיאות.

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

Contents

the email tool that makes email marketing simple