לדלג לתוכן הראשי

וובהוק (Webhook)

וובהוק, webhook, API, אינטגרציה, חיבור למערכת, סנכרון CRM, התראה על תרומה בזמן אמת, JSON, טוקנים, כותרת אבטחה, החזר כספי, תרומה חוזרת, שליחה חוזרת, מפתחים

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

איפה זה נמצא

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

מה ה-Webhook שלכם יכול לשלוח

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

התראה

event_type

מתי היא נשלחת

תרומה חדשה

donation

כל תרומה שהצליחה. פעילה תמיד כל עוד ה-Webhook מסומן פעיל.

תרומה חוזרת חדשה

recurring_started

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

תרומה חוזרת הופסקה

recurring_stopped

בכל פעם שתרומה חוזרת מופסקת, כולל הסיבה.

החזר כספי

refund

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

תרומה שנכשלה ולא הושלמה

rescue

תרומה נכשלה, וגם שעתיים לאחר מכן התורם עדיין לא תרם בהצלחה באותו יום. אלה המקרים המופיעים ב-Rescue My Donation.

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

הגדרת ה-Webhook

  1. הזינו את כתובת Webhook. היא חייבת להתחיל ב-https:// (או http://) ולהיות נגישה מהאינטרנט.

  2. בשדה פרויקט, השאירו ללא פרויקט (הכל) כדי לקבל את כל התרומות, או בחרו פרויקט כדי לקבל רק את התרומות לאותו פרויקט.

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

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

  5. ודאו ש-פעיל מסומן, ולחצו שמור Webhook.

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

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

תבנית לדוגמה

{
"event_type": "{event_type}",
"donation_id": "{donid}",
"transaction_id": "{trid}",
"amount": "{sum}",
"currency": "{currency}",
"frequency": "{frequency}",
"date": "{transaction_date}",
"project_id": "{projectid}",
"first_name": "{fname}",
"last_name": "{lname}",
"email": "{email}",
"phone": "{phone}",
"receipt_url": "{receipt_url}",
"custom1": "{cf1}"
}

טוקנים של טקסט חייבים להיות בתוך מירכאות, כמו בדוגמה. טוקנים של מספרים ושל true/false אפשר לכתוב עם מירכאות או בלעדיהן. אפשר להשתמש בטוקנים גם בכתובת, למשל https://yoursite.com/webhook?donation={donid}.

איך נשלחת כל בקשה

  • בקשת POST לכתובת שלכם, שגופה הוא התבנית שלכם (עם הטוקנים מוחלפים), עם Content-Type: application/json; charset=utf-8.

  • הכותרת Authorization: Bearer <כותרת האבטחה>. כותרת האבטחה נוצרת בפעם הראשונה ששומרים את ה-Webhook, ומוצגת בעמוד. בדקו אותה בכל בקשה כדי לוודא שהבקשה באמת הגיעה מאיתנו, ושמרו אותה בסוד. היא אינה משתנה כשעורכים ושומרים את ה-Webhook שוב.

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

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

  • בגלל ניסיונות חוזרים ושליחות חוזרות, אותה תרומה יכולה להגיע אליכם יותר מפעם אחת. השתמשו ב-donation_id כדי לא לשמור אותה פעמיים.

טוקנים

תרומה

{donid}

מספר התרומה. באירוע החזר: המספר של ההחזר עצמו.

{trid}

מספר עסקת התשלום

{sum}

סכום

{currency}

מטבע

{frequency}

1 = חד-פעמית, 2 = חודשית, 3 = שנתית

{installments}

מספר תשלומים

{transaction_date}

תאריך התרומה

{time_stamp}

מועד שליחת הבקשה, כ-Unix timestamp (UTC)

{approval_number}

מספר אישור העסקה בכרטיס

{projectid}

מספר הפרויקט (‎-1 כשאין פרויקט)

{campaignid}

מספר הקמפיין

{campaignname}

שם עמוד הקמפיין כפי שהוא מופיע בכתובת (‎-1 כשאין קמפיין)

{routing_name}

שם הניתוב המותאם, אם התרומה נותבה

{processor_name}

ספק הסליקה

{receipt_url}

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

{igul_letova}

True כשהתורם הצטרף לעיגול לטובה, אחרת False

{is_first_recurring_donation}

true בחיוב הראשון של תרומה חוזרת

{is_first_donation_to_charity}

true כשזו התרומה הראשונה של התורם לארגון שלכם

{cf1} … {cf10}

שדות מותאמים 1 עד 10 מטופס התרומה שלכם

תורם

{donor_id}

מספר התורם

{fname}, {lname}

שם פרטי ושם משפחה

{email}, {phone}

דוא"ל וטלפון

{address}, {city}, {state}, {zipcode}

כתובת

{country}, {country_id}

שם המדינה ומספר המדינה

{teudat_zeut_number}

מספר תעודת זהות, כשהתורם מסר אותו

אירועים

{event_type}

donation, recurring_started, recurring_stopped, refund או rescue

{event_date}

מתי האירוע קרה

{reason}

למה תרומה חוזרת הופסקה, או למה תרומה הוחזרה

{recurring_id}

מספר התרומה החוזרת

{refund_amount}

הסכום שהוחזר

{refunded_donation_id}

מספר התרומה שהוחזרה

{error_code}, {error_message}

למה התרומה נכשלה (אירוע rescue)

אירועים נוספים

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

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

  2. השאירו את תבנית התוכן שלו ריקה כדי לקבל את ה-JSON הסטנדרטי: event_type, event_date, reason, recurring_id, refund_amount, refunded_donation_id, error_code, error_message ואובייקט donation עם פרטי התרומה. אפשר גם לכתוב תבנית משלכם: טוקני האירועים וכל טוקני התרומה והתורם זמינים בה.

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

בדיקת מה שנשלח ושליחה חוזרת

הטבלה קריאות Webhook אחרונות מציגה את 10 הבקשות האחרונות: התרומה, הסטטוס, השגיאה (אם הייתה), המקור, ומועד השליחה.

ממתין

ממתינה לשליחה

בעיבוד

נשלחת עכשיו

נשלח

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

ממתין לניסיון חוזר

נכשלה ותישלח שוב אוטומטית

שגיאה

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

לא נשלח

התרומה הזו מעולם לא נשלחה ל-Webhook שלכם

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

פתרון בעיות

  • "יש לשמור את ה-Webhook לפני הבדיקה": שמרו קודם, ואז לחצו בדיקה.

  • "כתובת ה-Webhook מפנה לכתובת פנימית/מקומית שאינה מותרת": הכתובת חייבת להיות כתובת ציבורית באינטרנט, לא localhost ולא כתובת ברשת פנימית.

  • "נקודת הקצה החזירה שגיאה (HTTP …)": השרת שלכם קיבל את הבקשה ודחה אותה. בדקו את הלוגים של השרת ואת בדיקת כותרת האבטחה.

  • טוקן מגיע כטקסט, למשל {fname}: הטוקן כתוב עם שגיאה. לחצו בדוק תקינות JSON כדי למצוא טוקנים שאינם מזוהים.

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

האם קיבלת תשובה לשאלתך?