תיעוד
ה-API קטן במכוון. אלה העמודים שמכסים אותו, לפי הסדר שבו רוב האנשים צריכים אותם.
בקצרה
- מתחילים במדריך המסירה הראשונה: חשבון, יעד (endpoint), מסירה ראשונה.
- כל פעולה בלוח הבקרה היא קריאת API עם אותן הרשאות.
- אימות חתימה לוקח חמש עשרה שורות קוד, והמדריך מביא את כולן.
מתחילים כאן
המסירה הראשונה שלכם
חשבון, יעד, פרסום, וציר הזמן שמראה את האירוע מגיע.
צרכנים
אימות חתימות
שלוש הכותרות, פונקציית האימות, והטעות שכולם עושים פעם אחת.
אמינות
ניסיונות חוזרים ומניעת כפילויות
לוח הניסיונות, מה נשמר בין ניסיון לניסיון, ואיך צרכן נמנע מטיפול כפול.
תפעול
תור הכשלים והחזרה לפעולה
מה קורה כשהלוח נגמר, ושני הכפתורים שמתקנים את המצב.
נכנס
מדריכי פלטפורמות
קבלת וובהוקים מאומתים מחמישה עשר ספקים.
הכול
כל המדריכים
בדיקות, דיבוג, בטיחות תעבורה יוצאת, וכל השאר.
ממשק ה-API
מזדהים עם bearer token: מפתח API למכונות, סשן ללוח הבקרה.
| נתיב | מה הוא עושה |
|---|---|
POST /v1/events | פרסום אירוע. עונה 202 ברגע שהוא נשמר. השדות האופציונליים attributes ו-metrics מאפשרים להציג אותו בגרף בדשבורד |
POST /v1/events/batch | פרסום של כמה אירועים; כל פריט נבחן בפני עצמו |
GET /v1/events | יומן האירועים, עם סינון לפי סוג |
GET /v1/events/{id}/attempts | ציר הזמן של המסירה לאירוע אחד |
POST /v1/events/{id}/replay | שליחה חוזרת של אירוע |
POST /v1/events/replay-missing | השלמת פער: החזרה לתור של אירועים שאין להם אף ניסיון |
POST /v1/endpoints | יצירת יעד. סוד החתימה מוחזר פעם אחת בלבד, וכך גם המפתח הפרטי של ed25519 אם ביקשתם signing_scheme: "ed25519" |
PATCH /v1/endpoints/{id} | שינוי הכתובת, לוח הניסיונות החוזרים, ה-filter, העיבוד המקדים או שיטת החתימה |
POST /v1/portal-links | הנפקת הרשאה לפורטל לקוחות. embed: true יחד עם brand מחזיר קטע iframe עם הלוגו והצבע שלכם; manage: true מאפשר למחזיק להעביר את היעד שלו, להחליף מפתח ולהשהות מסירות; consumer_id יחד עם create: true מאפשר לו להוסיף יעדים משלו, וכל קישור עתידי לאותו צרכן רואה אותם |
POST /v1/portal/endpoints | יצירת יעד מתוך הפורטל, תחת הרשאת צרכן. כתובת, סוגי אירועים ותיאור בלבד: צר יותר מהממשק של המפעיל, במכוון |
GET /v1/poll/{id} | יעד משיכה שנקרא לפי סמן, בשביל צרכן שאין לו כתובת ציבורית. ההזדהות בהרשאת פורטל |
POST /v1/endpoints/{id}/rotate-secret | החלפת סוד עם חלון חפיפה |
POST /v1/endpoints/{id}/recover | החזרה לפעולה של יעד מושבת ושליחה חוזרת של מה שבתור הכשלים שלו |
GET /v1/endpoints/{id}/health | אחוז הצלחה, אחוזוני זמן תגובה, כשלים רצופים |
POST /v1/sources | יצירת מקור נכנס מאומת |
POST /ingest/{id} | הכתובת שאליה הספק החיצוני שולח |
GET /v1/dlq · POST /v1/dlq/replay | צפייה בתור הכשלים וריקון שלו |
GET /v1/stats · GET /v1/usage | נפחים ויחידות לחיוב |
POST /v1/keys | הנפקת מפתח עם הרשאות מוגבלות. אף פעם לא חזק יותר מהמפתח שיצר אותו |
/v1/members | ניהול צוות |
/v1/private-repos | Private Repo: רישום מאגר תחת גיבוב, דיווח על מניפסט של נקודת שמירה, קריאת היסטוריה ותקינות המכונות. מזהים אטומים וספירות בלבד: שום נתיב קובץ, הודעת commit או קוד לא מגיעים לנתיבי ה-API האלה |
/v1/ai-spend | הוצאות AI לפי מודל, תגית פיצ׳ר, ספר חשבונות או אדם ממופה, ויתרת הגייטוויי בתשלום מראש. קריאה בלבד |
שגיאות הן מסמכי problem לפי RFC 9457: סוג, כותרת, סטטוס ופירוט קריא. משאב ששייך ללקוח אחר מדווח כ"לא נמצא".
סוגי האירועים שהמחברים מפיקים
מחבר משיכה מדווח את מה שהספק מדווח: סיכומים סגורים, אף פעם לא שורה לכל קריאה. כדאי לפרט את אירועי ה-AI, כי כסף וטוקנים מופרדים שם במכוון.
| סוג אירוע | מה הוא נושא |
|---|---|
llm.usage_reported | טוקנים לצמד סגור של (חלון זמן, מודל): קלט, פלט, מטמון, חשיבה, בקשות. בלי עלות: סכימה של עמודת עלות לכל מודל הייתה מכפילה את החשבון |
llm.cost_reported | הכסף, באירוע משלו. sum(cost_usd) הוא החשבון |
llm.credits_reported | היתרה בתשלום מראש בגייטוויי עם חיוב מאוחד. מפלס, לא זרימה: יתרה שמתרוקנת תוקעת את הפרודקשן בשקט |
המקור ai-gateway קורא את ה-API של הדיווח בגייטוויי עם חיוב מאוחד, כך
שהוצאה שיצאה מספר החשבונות של הספק עדיין גלויה. האירועים שלו תמיד נושאים
provider: "ai-gateway", והספק המקורי נמצא בשדה upstream_provider. כך לקוח
שמריץ את שני ספרי החשבונות לא יספור אף פעם בקשה אחת פעמיים. נקראים רק סיכומים: יומני הבקשות מכילים
פרומפטים, ואנחנו לא קוראים אותם אף פעם.
לסוכני AI
HookGet מגיע עם שרת MCP: אותו API מאחורי 57 כלים, כך שעוזר AI יכול לפרסם אירוע, לקרוא ציר זמן של מסירה, לאבחן יעד, לקרוא כמה עלה ה-AI לפי פיצ׳ר, או להשלים פער. פעולות ששולחות שוב תעבורה אמיתית דורשות ארגומנט אישור מפורש, לא רק תווית מנומסת.
שאלות
מאיפה מתחילים?
מהמדריך המסירה הראשונה: חשבון, יעד, פרסום, וציר הזמן שמראה את האירוע מגיע. הצעד הבא, בצד הצרכן, הוא אימות חתימות.
איך מזדהים מול ה-API?
עם bearer token: מפתח API למכונות, וסשן ללוח הבקרה. כל פעולה בלוח הבקרה היא קריאת API
עם אותן הרשאות. מפתח חדש שנוצר דרך POST /v1/keys אף פעם לא חזק יותר מהמפתח
שיצר אותו.
איך נראות שגיאות?
כמסמכי problem לפי RFC 9457: סוג, כותרת, סטטוס ופירוט קריא. משאב ששייך ללקוח אחר מדווח כ"לא נמצא".
מה ההבדל בין שליחה חוזרת להשלמת פערים?
POST /v1/events/{id}/replay שולח שוב אירוע מסוים. POST
/v1/events/replay-missing מתקן פער: הוא מחזיר לתור אירועים שאין להם אף ניסיון מסירה.
לתור הכשלים יש מסלולים משלו, GET /v1/dlq ו-POST /v1/dlq/replay.
סוכן AI יכול להפעיל את HookGet?
כן. HookGet מגיע עם שרת MCP שעוטף את אותו API ב-57 כלים. פעולות ששולחות שוב תעבורה אמיתית דורשות ארגומנט אישור מפורש.
להתחיל למסור וובהוקים היום
מפנים את הוובהוקים ל-HookGet ורואים את המסירה הראשונה מגיעה, חתומה, תוך פחות מדקה.
פתיחת חשבון חינם לנסות את בודק הוובהוקים החינמי
10,000 מסירות בחודש בחינם, בלי כרטיס אשראי. המסלול החינמי חוסם ולא מחייב, כך שניסיון לא יכול להסתיים בחשבונית.