פיתוח התראות callback/webhook על תשלומים

Webhook של תשלומי קריפטו: היכן נשברת שרשרת האירועים

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

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

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

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

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

מה משתנה לאחר ההטמעה: מהירות, שלמות, בקרה

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

מסירה אמינה של אירועים מבוססת על תור עם אישור קבלה: כתובת ה-webhook של המקבל נקראת שוב עם השהיה גדלה, וכל ניסיון נרשם ביומן עם קוד התגובה. שיעור ההתראות שנמסרות מפסיק להיות תלוי בזמינות של שירות אחד — במשלוחים חוזרים הוא מגיע ל-99.9% לעומת 90-95% בקריאה בודדת.

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

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

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

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

מה משותף לכל המצבים

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

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

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

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

1. ביקורת של תוכנית התשלומים. מנתחים כיצד כיום מגיעות התראות על תשלומים, היכן נשמר מצב ההזמנה, אילו בדיקות מתבצעות לפני הזיכוי. מתעדים תרחישים: מסירה חוזרת, אובדן אירוע, rollback של בלוקים ברשת, העברה ידנית מחוץ לקופה.
2. תכנון חוזה ההתראה. מתאמים את הרכב השדות, חתימת הבקשה במפתח סודי, מזהה אירוע לצורך אידמפוטנטיות וגרסאות — כדי שהוספת שדות חדשים לא תשבור מקבלים שכבר עובדים.
3. הגדרת תור ומסירות חוזרות. התראות יוצאות דרך תור עם אישור עיבוד, חזרות נשלחות בהשהיה גדלה, ומה שלא נמסר — לענף נפרד. השירות של הלקוח יכול להיות מושבת לזמן מה, האירוע יחכה לו.
4. סביבת בדיקות. מרימים אמולטור רשת עם תנאים נשלטים: השהיית אישורים, rollback של בלוק, אירוע כפול, אי-זמינות של המקבל. מריצים כל ענף ומשווים יומנים של שני הצדדים.
5. מימוש וקבלה. כותבים קוד, מאגר סטטוסים, מדדים והתראות על עומסים בתור. בשלב הקבלה מנתחים אירועים יחד עם הצוות שלכם.
6. מסירה לתפעול. מעבירים קונפיגורציות, תרשים זרימות והוראות לשליחה מחדש ידנית של אירוע; מתעדים תוכנית rollback אם עדכון המקבל נכשל.

ערכת ההגדרות והתיעוד שנשארת אצלכם

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

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

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

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

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

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

מה שינו בתרשים המסירה

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

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

מה קרה לפי המדדים

שיעור התשלומים שנזקפים אוטומטית עלה מ-92% ל-99.9%. אירועים שאבדו — מאחד בערך לכל 400 לאפס במשך חצי שנת תצפית עם פריסות מתמשכות. ההתאמה הידנית הצטמצמה מכמה שעות מדי יום לבדיקה קצרה לפי היומן פעם בשבוע: צריך להסתכל רק על אירועים בסטטוס «דורש תשומת לב», והם בודדים.

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

מה לעשות אם קבלת התשלומים כבר מוגדרת, אבל אירועים הולכים לאיבוד?

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

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

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

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

שאלות נפוצות של מהנדסים על מסירת אירועים

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

באיזה סדר מגיעים האירועים?

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

מה לעשות אם השירות שלנו אינו זמין?

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

נדון במשימה ונחזור עם אומדן ותוכנית עבודה

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

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

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