Какво е 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. Доставчикът ви дава тайна за подписване. Съхранявате я като secret на сървъра си — вижте environment variables и secrets.
4. Настъпва събитие. Доставчикът изпраща HTTP заявка към адреса ви с JSON тяло, което го описва, и заглавие с подпис.
5. Приложението ви проверява подписа, записва ID на събитието, бързо отговаря с код за успех (200) и след това върши работата.
6. Ако приложението ви не отговори с успех, много доставчици опитват отново по-късно.

Подписи

Подписът доказва, че заявката е от доставчика и не е променена. Stripe например изчислява HMAC (вид ключиран отпечатък) с SHA-256 върху тялото на заявката и времево клеймо, използвайки тайната за подписване, и го изпраща в заглавието Stripe-Signature. Приложението ви извършва същото изчисление със своето копие на тайната; ако резултатите съвпаднат, заявката е истинска. Тъй като времевото клеймо също е подписано, можете да отхвърляте стари заявки, които някой е записал и пуска по-късно — библиотеките на Stripe по подразбиране допускат толеранс от пет минути според документацията му към септември 2026.

Едно практическо подробност: подписът се изчислява върху суровото тяло на заявката. Ако вашата рамка парсира и преформатира JSON преди проверката, проверката се проваля. Това е много често срещана грешка.

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

Доставчиците се различават, затова проверете документацията на всеки. Към септември 2026:

Документацията на Stripe също казва, че събитията не са гарантирано в реда, в който са настъпили, и че едно и също събитие понякога може да пристигне повече от веднъж, затова препоръчва проследяване на ID-тата на събитията.

Общият урок важи за всеки доставчик: събитията могат да пристигнат със закъснение, повече от веднъж и в неправилен ред. Обработчикът ви трябва да е идемпотентен — обработката на едно и също събитие два пъти да има същия ефект като обработката му веднъж.

Пример: отключване на платен курс

Продавате онлайн курс. Студент натиска Купи, плаща в хостнатата страница за плащане на Stripe и се връща на сайта ви.

Крехкият начин: страницата „благодаря“ отключва курса. Ако студентът затвори браузъра по време на пренасочването, е платил, но няма достъп. Ако някой познае адреса на страницата „благодаря“, получава достъп без плащане.

Начинът с webhook:

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

По-късно, ако абонамент бъде отказан или карта се провали, други webhook събития казват на приложението ви да премахне или да спре достъпа. Така продуктите с абонамент остават синхронизирани с фактурирането — вижте какво е SaaS и как да добавите плащания към приложението си.

Основни термини

• Endpoint (крайна точка): адресът във вашето приложение, който получава webhook-овете.
• Събитие / payload: какво се е случило и данните, които го описват (обикновено JSON).
• Тайна за подписване (signing secret): споделената тайна, използвана за проверка на подписите.
• Идемпотентен: безопасен за изпълнение повече от веднъж със същия резултат.
• Polling: многократно питане на API за промени, вместо да чакате webhook.
• Tunnel: инструмент, който дава на лаптопа временен публичен адрес, за да могат webhook-овете да стигнат до него по време на разработка.

Чести грешки и заблуди

• Непроверяване на подписите. Адресът на крайната точка не е тайна. Проверката е това, което прави заявката надеждна.
• Бавна работа преди отговор. Изпращането на имейли или генерирането на PDF файлове преди отговор може да доведе до timeout, който предизвиква повторни опити, които създават дубликати.
• Предположение за точно веднъж и в ред. Записвайте ID-тата на събитията и не разчитайте на реда на пристигане.
• Използване на preview адрес. Webhook-овете се нуждаят от стабилен публичен адрес. Частните preview и localhost не са достъпни от интернет; използвайте публикувания адрес (или tunnel при тестване).
• Смесване на тестови и живи тайни. Доставчиците често издават различни тайни за подписване за тестов и live режим. Съхранявайте и двете и използвайте правилната.
• Сляпо доверие в payload-а за важни решения. При действия с висок залог е разумно след получаване на събитието да вземете последното състояние от API на доставчика.

Какво да поискате от AI билдъра си

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

След това тествайте: изпратете тестово събитие от таблото на доставчика, изпратете същото отново и изпратете заявка с грешен подпис. Само първото трябва да промени нещо.

Webhook-ове в Mythex

Mythex не работи с отделна услуга за webhook-ове; помолете агента да добави webhook крайна точка в собствения бекенд на приложението и насочете доставчика към вашия публикуван адрес, тъй като webhook-овете се нуждаят от публичен адрес. Тайната за подписване отива в secrets на проекта ви, а ако я промените в живо приложение, публикувайте отново. Рецептата в документацията за обработка на webhook-ове съдържа стартов prompt, а шаблони за магазини са добра отправна точка за приложения, които приемат плащания.

Въпроси