Што е webhook? Како апликациите меѓусебно се известуваат

Webhook е автоматска порака што една услуга ја испраќа до вашата апликација во моментот кога нешто ќе се случи. Кога плаќањето на еден клиент ќе успее, Stripe испраќа webhook на адреса во вашата апликација со порака „плаќањето е успешно, еве ги деталите“, а вашата апликација реагира — го означува нарачката како платена, испраќа потврда, отклучува сметка. Накратко: API е кога вашата апликација му постави прашање на друга услуга; webhook е кога другата услуга ја повикува вашата апликација за да ѝ каже нешто.

Зошто е важно кога градите со AI

Во моментот кога вашата апликација прима плаќања, добива форми од друг алат или се поврзува со услуги како GitHub, Shopify или календар, ќе налетате на webhook-ови. Обично се точниот начин да дознаете дека нешто се случило — но тука и апликациите изградени со AI најчесто суптилно грешат:

• Крајната точка прифаќа секое барање, па секој може да испрати лажен настан „плаќањето е успешно“.
• Апликацијата дава пристап на страницата за пренасочување по плаќањето, наместо преку webhook, па луѓето што ќе го затворат табот рано никогаш не го добиваат она што го платиле, а оние што ќе ја најдат адресата за успех го добиваат бесплатно.
• Истиот настан пристигнува двапати и клиентот добива две нарачки или две е-пошти.

Кога знаете како работат webhook-овите, можете однапред да побарате заштитите.

Секојдневна аналогија: SMS за испорака

Во две работи можете да дознаете дали пратката ви стигнала. Можете на секои десет минути да одите до влезната врата да проверите (тоа е polling — вашата апликација постојано го повикува API-то за да праша „има ли нешто ново?“). Или куриерот може да ви испрати SMS кога е доставена (тоа е webhook).

SMS-от е очигледно подобар — сѐ додека можете да му верувате. Ако некој би можел да ви испрати порака „пратката е доставена“, би сакале некаков начин да знаете дека навистина дошла од куриерот. А ако телефонот ви бил исклучен кога пристигнал SMS-от, би сакале куриерот да обиде повторно подоцна. Овие две работи — верификација и повторни обиди — се најголемиот дел од тоа што webhook-овите ги прави тешки.

Како работи webhook, чекор по чекор

1. Создавате крајна точка во позадината на вашата апликација: адреса како https://yourapp.com/webhooks/stripe што прифаќа POST барања.
2. Ја регистрирате таа адреса кај давателот и избирате кои настани ги сакате (на пример, „checkout завршен“ и „претплатата е откажана“).
3. Давателот ви дава тајна за потпишување. Ја чувате како тајна на вашиот сервер — видете променливи на околината и тајни.
4. Настанот се случува. Давателот испраќа HTTP барање до вашата адреса со JSON тело што го опишува, плус заглавие со потпис.
5. Вашата апликација го проверува потписот, го запишува ID-то на настанот, брзо одговара со успешен код (200), па потоа ја врши работата.
6. Ако вашата апликација не одговори со успех, многу даватели пробуваат повторно подоцна.

Потписи

Потписот докажува дека барањето дошло од давателот и не е изменето. Stripe, на пример, пресметува HMAC (вид клучен отпечаток) со SHA-256 над телото на барањето и временска ознака, со користење на тајната за потпишување, и го испраќа во заглавието Stripe-Signature. Вашата апликација ја прави истата пресметка со својата копија на тајната; ако резултатите се совпаѓаат, барањето е автентично. Бидејќи и временската ознака е потпишана, можете да одбиете стари барања што некој ги снимил и ги повторува подоцна — библиотеките на Stripe стандардно имаат толеранција од пет минути, според нивната документација од септември 2026.

Една практична подробност: потписот се пресметува над суровото тело на барањето. Ако вашата рамка го парсира и повторно го форматира JSON-от пред проверката, проверката ќе падне. Ова е многу честа грешка.

Повторни обиди, дупликати и редослед

Давателите се разликуваат, па проверете ја документацијата на секој. Од септември 2026:

Документацијата на Stripe вели и дека настаните не се гарантирано пристигнуваат по редоследот по кој се случиле, и дека истиот настан понекогаш може да пристигне повеќе од еднаш, па препорачува да се следат ID-ata на настаните.

Општата поука важи за секој давател: настаните можат да пристигнат задоцнето, повеќе од еднаш и надвор од редослед. Вашиот обработувач треба да биде идемпотентен — обработката на истиот настан двапати има исто дејство како обработката еднаш.

Работен пример: отклучување на платен курс

Продавате онлајн курс. Студент клика Купи, плаќа на хостираната страница за плаќање на Stripe и е вратен на вашиот сајт.

Кревкиот начин: страницата „Ви благодариме“ го отклучува курсот. Ако студентот го затвори прелистувачот за време на пренасочувањето, платил, но нема пристап. Ако некој ја погоди URL адресата на страницата „Ви благодариме“, добива пристап без да плати.

Начинот со webhook:

1. Кога Stripe ќе го потврди плаќањето, испраќа настан checkout.session.completed до /webhooks/stripe.
2. Вашата позадина го проверува потписот со тајната за потпишување. Ако не успее, одговара со 400 и не прави ништо.
3. Проверува дали тој ID на настан веќе е обработен. Ако да, одговара со 200 и застанува.
4. Го зачувува ID-то на настанот, одговара со 200, па потоа му дава пристап на студентот и испраќа добредојдена е-пошта.
5. Страницата „Ви благодариме“ само вели „Плаќањето е примено — курсот ќе се појави наскоро“ и го проверува статусот на пристапот на студентот.

Подоцна, ако претплатата се откаже или картичката не успее, други webhook настани ѝ велат на вашата апликација да го отстрани или паузира пристапот. Вака производите со претплата остануваат синхронизирани со наплатата — видете што е SaaS и како да додадете плаќања во вашата апликација.

Клучни термини

• Endpoint: адресата во вашата апликација што ги прима webhook-овите.
• Настан / payload: што се случило и податоците што го опишуваат (обично JSON).
• Тајна за потпишување: заедничката тајна што се користи за проверка на потписите.
• Идемпотентен: безбедно е да се изврши повеќе пати со ист резултат.
• Polling: постојано барање на API за промени, наместо да се чека webhook.
• Тунел: алатка што на лаптопот му дава привремена јавна адреса, за webhook-овите да стигнат до него при развој.

Вообичаени грешки и погрешни верувања

• Непроверување на потписите. Адресата на крајната точка не е тајна. Проверката е она што го прави барањето доверливо.
• Бавна работа пред одговор. Испраќање е-пошта или генерирање PDF пред одговорот може да предизвика истек на времето, што предизвикува повторни обиди, што предизвикува дупликати.
• Претпоставка дека се случува точно еднаш, по редослед. Запишувајте ги ID-тата на настаните и не се потпирајте на редоследот на пристигнување.
• Користење на адреса за преглед. Webhook-овите имаат потреба од стабилна, јавна адреса. Приватните прегледи и localhost не се достапни од интернет; користете ја објавената адреса (или тунел при тестирање).
• Мешање на тест и живи тајни. Давателите често издаваат различни тајни за потпишување за тест и live режим. Чувајте ги двете и користете ја вистинската.
• Слепо верување на payload-от за важни одлуки. За дејства со големи последици, разумно е по добивањето на настанот да се земе последната состојба од API-то на давателот.

Што да побарате од вашиот AI градител

Додај POST /webhooks/stripe крајна точка на серверот. Провери го Stripe потписот со суровото тело на барањето и тајната STRIPE_WEBHOOK_SECRET. Одбивај неважечки потписи со 400. Зачувувај го ID-то на секој настан и прескокнувај настани што веќе се обработени. Одговори со 200 брзо, па обработи checkout.session.completed со означување на нарачката како платена и испраќање на потврдата. Запишувај го типот на настанот. Не давај пристап од страницата за успешно плаќање.

Потоа тестирајте: испратете тест настан од контролната табла на давателот, испратете го истиот повторно и испратете барање со погрешен потпис. Само првиот треба нешто да промени.

Webhook-овите во Mythex

Mythex не работи посебна услуга за webhook-ови; го барате од агентот да додаде webhook крајна точка во позадината на вашата апликација, а давателот го насочувате кон вашата објавена адреса, бидејќи webhook-овите имаат потреба од јавна адреса. Тајната за потпишување се става во тајните на проектот, а ако ја промените на жива апликација, објавете повторно. Рецептот во документацијата за обработка на webhook-ови содржи почетна порака, а шаблоните за продавници се добра почетна точка за апликации што примаат плаќања.

Прашања