וובהוק (Webhook) שולח את התרומות שלכם אוטומטית למערכת שלכם (CRM, מסד נתונים או אפליקציה), זמן קצר אחרי כל תרומה. ההגדרה נעשית על ידכם בחשבון, בלי צורך בעזרה מאיתנו.
איפה זה נמצא
עברו אל הגדרות › סינכרון › וובהוק. אם אינכם רואים את האפשרות, בקשו מבעל החשבון לתת למשתמש שלכם גישה אליה.
מה ה-Webhook שלכם יכול לשלוח
כתובת אחת יכולה לקבל חמישה סוגי התראות. בכל בקשה יש שדה event_type, כך שהמערכת שלכם יודעת להבחין ביניהן.
התראה | event_type | מתי היא נשלחת |
תרומה חדשה |
| כל תרומה שהצליחה. פעילה תמיד כל עוד ה-Webhook מסומן פעיל. |
תרומה חוזרת חדשה |
| החיוב המוצלח הראשון של תרומה חוזרת חדשה, וגם כאשר תרומה חוזרת שהופסקה מופעלת מחדש. |
תרומה חוזרת הופסקה |
| בכל פעם שתרומה חוזרת מופסקת, כולל הסיבה. |
החזר כספי |
| תרומה הוחזרה. החזר אינו נשלח כתרומה חדשה עם סכום שלילי. |
תרומה שנכשלה ולא הושלמה |
| תרומה נכשלה, וגם שעתיים לאחר מכן התורם עדיין לא תרם בהצלחה באותו יום. אלה המקרים המופיעים ב-Rescue My Donation. |
את ארבע האחרונות מפעילים בנפרד, בחלק אירועים נוספים (ראו בהמשך).
הגדרת ה-Webhook
הזינו את כתובת Webhook. היא חייבת להתחיל ב-
https://(אוhttp://) ולהיות נגישה מהאינטרנט.בשדה פרויקט, השאירו ללא פרויקט (הכל) כדי לקבל את כל התרומות, או בחרו פרויקט כדי לקבל רק את התרומות לאותו פרויקט.
כתבו את תבנית המטען (JSON): ה-JSON שנשלח אליכם, עם טוקנים בסוגריים מסולסלים במקום שבו יופיעו פרטי התרומה. לחצו טען דוגמה כדי להתחיל מתבנית מוכנה, ו-הוסף טוקן כדי להוסיף טוקן במקום שבו נמצא הסמן.
לחצו בדוק תקינות JSON כדי לוודא שהתבנית היא JSON תקין ושכל הטוקנים מזוהים.
ודאו ש-פעיל מסומן, ולחצו שמור Webhook.
לחצו בדיקה. נשלח את התבנית שלכם, עם ערכים לדוגמה, לכתובת שלכם, ונציג את סטטוס ה-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כדי לא לשמור אותה פעמיים.
טוקנים
תרומה
| מספר התרומה. באירוע החזר: המספר של ההחזר עצמו. |
| מספר עסקת התשלום |
| סכום |
| מטבע |
| 1 = חד-פעמית, 2 = חודשית, 3 = שנתית |
| מספר תשלומים |
| תאריך התרומה |
| מועד שליחת הבקשה, כ-Unix timestamp (UTC) |
| מספר אישור העסקה בכרטיס |
| מספר הפרויקט (-1 כשאין פרויקט) |
| מספר הקמפיין |
| שם עמוד הקמפיין כפי שהוא מופיע בכתובת (-1 כשאין קמפיין) |
| שם הניתוב המותאם, אם התרומה נותבה |
| ספק הסליקה |
| קישור להורדת הקבלה |
| True כשהתורם הצטרף לעיגול לטובה, אחרת False |
| true בחיוב הראשון של תרומה חוזרת |
| true כשזו התרומה הראשונה של התורם לארגון שלכם |
| שדות מותאמים 1 עד 10 מטופס התרומה שלכם |
תורם
| מספר התורם |
| שם פרטי ושם משפחה |
| דוא"ל וטלפון |
| כתובת |
| שם המדינה ומספר המדינה |
| מספר תעודת זהות, כשהתורם מסר אותו |
אירועים
| donation, recurring_started, recurring_stopped, refund או rescue |
| מתי האירוע קרה |
| למה תרומה חוזרת הופסקה, או למה תרומה הוחזרה |
| מספר התרומה החוזרת |
| הסכום שהוחזר |
| מספר התרומה שהוחזרה |
| למה התרומה נכשלה (אירוע rescue) |
אירועים נוספים
אחרי שה-Webhook נשמר, החלק אירועים נוספים מאפשר לבחור אילו מארבע ההתראות הנוספות לקבל. הן נשלחות לאותה כתובת עם אותה כותרת אבטחה.
סמנו שלח אירוע זה לכל אירוע שאתם רוצים לקבל.
השאירו את תבנית התוכן שלו ריקה כדי לקבל את ה-JSON הסטנדרטי:
event_type,event_date,reason,recurring_id,refund_amount,refunded_donation_id,error_code,error_messageואובייקטdonationעם פרטי התרומה. אפשר גם לכתוב תבנית משלכם: טוקני האירועים וכל טוקני התרומה והתורם זמינים בה.לחצו שמור אירועים. אפשר לבדוק כל אירוע באותה דרך שבודקים את ה-Webhook.
בדיקת מה שנשלח ושליחה חוזרת
הטבלה קריאות Webhook אחרונות מציגה את 10 הבקשות האחרונות: התרומה, הסטטוס, השגיאה (אם הייתה), המקור, ומועד השליחה.
ממתין | ממתינה לשליחה |
בעיבוד | נשלחת עכשיו |
נשלח | השרת שלכם קיבל אותה |
ממתין לניסיון חוזר | נכשלה ותישלח שוב אוטומטית |
שגיאה | נכשלה. בעמודה שגיאה מופיע מה השרת שלכם החזיר. |
לא נשלח | התרומה הזו מעולם לא נשלחה ל-Webhook שלכם |
כדי למצוא תרומה ישנה יותר, הזינו את מספרה ב-חיפוש תרומה ולחצו חיפוש. לחצו שלח שוב כדי לשלוח תרומה פעם נוספת. היא נכנסת לתור ונשלחת תוך כמה דקות.
פתרון בעיות
"יש לשמור את ה-Webhook לפני הבדיקה": שמרו קודם, ואז לחצו בדיקה.
"כתובת ה-Webhook מפנה לכתובת פנימית/מקומית שאינה מותרת": הכתובת חייבת להיות כתובת ציבורית באינטרנט, לא localhost ולא כתובת ברשת פנימית.
"נקודת הקצה החזירה שגיאה (HTTP …)": השרת שלכם קיבל את הבקשה ודחה אותה. בדקו את הלוגים של השרת ואת בדיקת כותרת האבטחה.
טוקן מגיע כטקסט, למשל {fname}: הטוקן כתוב עם שגיאה. לחצו בדוק תקינות JSON כדי למצוא טוקנים שאינם מזוהים.
מעדיפים לא לכתוב קוד? השתמשו באפליקציית Zapier שלנו כדי לשלוח תרומות לאלפי אפליקציות אחרות.
