המסירה הראשונה שלכם

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

1. הוספת יעד

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

curl -X POST https://api.hookget.com/v1/endpoints \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://orders.example.com/webhooks","event_types":["order.created"]}'

# {"id":"ep_…","secret":"whsec_…"}   ← the secret appears exactly once

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

2. פרסום אירוע

curl -X POST https://api.hookget.com/v1/events \
  -H "authorization: Bearer $HOOKGET_KEY" \
  -H "content-type: application/json" \
  -d '{"type":"order.created","payload":{"id":"ord_10241","total":149.9}}'

# 202 — stored, then fanned out to every subscribed endpoint

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

3. מעקב אחרי המסירה

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

curl https://api.hookget.com/v1/events/msg_01M0…/attempts \
  -H "authorization: Bearer $HOOKGET_KEY"