Изграждане на партньори API Webhooks за дистрибутори на AI API: Подписани събития, трайна доставка и безопасно възпроизвеждане

Проучване на партньор API за всяка промяна на баланс, клиент, ключ, бюджет и използване създава неудобна контролна верига: важните действия пристигат със закъснение, непроменените ресурси се извличат многократно и едновременните актуализации могат да се наблюдават в грешен ред. Изходящите уебкукички намаляват това забавяне, но само ако са изградени като трайна система за уведомяване, а не HTTP обратно извикване, добавено към манипулаторите на заявки.

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

Първо дефинирайте договора за доставка

Установен факт: общите спецификации на уеб кукички и големите издатели на уеб кукички приемат доставка поне веднъж. Повторните опити могат да доведат до дубликати и независими доставки могат да пристигнат с неправилен ред.

Препоръка: публикувайте следния договор, преди да изложите управление на крайна точка API:

• Всяко бизнес събитие има стабилен, неизменен идентификатор на събитие.
• Същият идентификатор на събитие се запазва при автоматични повторни опити и ръчни повторения.
• Доставката е поне веднъж; не е обещана доставка точно веднъж.
• Подреждането не е гарантирано в крайни точки или типове събития.
• Успешният отговор означава, че получателят трайно е приел събитието, а не непременно, че цялата работа надолу по веригата е приключила.
• Webhooks са известия; Партньор API чете и експортирането на счетоводна книга остава валидно.

Този договор отговаря на AI API платформа за дистрибутори, тъй като контролът на достъпа и финансовите събития изискват както бързо уведомяване, така и надежден път за възстановяване.

Започнете с тесен каталог на събития

Не превръщайте всяка актуализация на база данни в публично събитие. Публикувайте преходи, по които партньорът може да действа и да ги дефинира точно.

Праговите събития се нуждаят от изрично правило за пресичане. Излъчване, когато предишната стойност е била под 80 процента и новата стойност е на или над 80 процента, например, вместо да се излъчва при всеки следващ запис на употреба. Определете дали обръщанията могат да активират отново прага и дали корекциите могат да генерират ново пресичане.

Препоръка: избягвайте да поставяте пълни API ключове, идентификационни данни на доставчика, необработени подкани или подробни доказателства за злоупотреба в полезни натоварвания. Предпочитайте идентификатори на ресурси и минимални моментни снимки на състоянието. Получателят може да използва Партньор API, за да извлече чувствителни или бързо променящи се подробности.

Създаване на събития от ангажирано състояние

Публикуването директно от манипулатор на заявки създава два прозореца за отказ. Обратното извикване може да избяга, преди транзакцията на базата данни да се ангажира, или транзакцията може да се ангажира, докато процесът е неуспешен, преди да изпрати обратното извикване. Транзакционната изходяща кутия затваря и двата прозореца.

Поредица от транзакционни изходящи

1. Започнете транзакцията на контролната равнина или счетоводната книга.
2. Прилагане на валидната промяна на състоянието.
3. Вмъкване на неизменно събитие в таблица с изходяща кутия в същата транзакция.
4. Ангажирайте веднъж.
5. Позволете на работник на издателя да изиска поети редове за изходяща кутия.
6. Разрешаване на отговарящи на условията крайни точки с помощта на партньорския обхват на събитието и филтрите за абонамент.
7. Създайте един запис за доставка за всяка двойка събитие-крайна точка.

Уникално ограничение на (event_id, endpoint_id) предотвратява дублиране на разклоняване при повторен опит на работниците. Състоянието на публикация в изходящата кутия трябва да се актуализира със семантика за сравнение и задаване или заключване на редове, така че множество работници да могат да си сътрудничат безопасно.

outbox_event(
  event_id, partner_id, type, subject_id,
  occurred_at, schema_version, payload, correlation_id,
  published_at
)

delivery(
  delivery_id, event_id, endpoint_id, state,
  attempt_count, next_attempt_at, last_status,
  last_latency_ms, last_error_category
)

Изходящата кутия добавя записи в базата данни, работа по почистване и наблюдение на неизпълнени задачи. Тези разходи са оправдани, когато уведомленията имат финансови последици или последици за контрола на достъпа. Обратното извикване с най-добри усилия все още може да бъде приемливо за телеметрия на продукти за еднократна употреба, но не трябва да споделя твърденията за надеждност на системата за уеб кукичка на Partner API.

Използвайте стабилна обвивка на събитието

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

{
  "event_id": "evt_01J...",
  "type": "usage.finalized",
  "occurred_at": "2026-10-15T14:22:31Z",
  "partner_id": "partner_42",
  "subject": {
    "type": "usage_record",
    "id": "usage_9182"
  },
  "schema_version": "1",
  "correlation_id": "op_7fd...",
  "data": {
    "customer_id": "cus_204",
    "currency": "USD",
    "final_cost": "1.274800"
  }
}

Използвайте десетични низове или малки единици цели числа за пари. Документирайте политиката за валута, точност и закръгляване. Идентификационният номер на корелация трябва да свързва събитието с първоначалната операция на партньор API или публикуване в счетоводната книга, без да се превръща в идентичност на събитието.

Налагане на безопасен за клиента вентилатор

Разрешаване на абонаменти в партньорския обхват на събитието, преди да се изградят специфични за крайната точка полезни натоварвания. Идентификатор на крайна точка, предоставен от съобщение за работа или опашка, не трябва да е достатъчен, за да разреши доставката. Работникът трябва да зареди крайната точка с предикат, еквивалентен на endpoint.partner_id = event.partner_id, и да провери дали е активен и абониран за типа събитие.

Това е изходящият аналог на упълномощаването на клиента в Партньор API автоматизация: собствеността върху обекта трябва да бъде възстановена на всяка асинхронна граница.

Подпишете точните байтове, които изпращате

Установен факт: стандартната спецификация на Webhooks дефинира заглавки webhook-id, webhook-timestamp и webhook-signature и подписва заедно идентификатора на събитието, клеймото за време и време на опита и основния текст на заявката.

Присвояване на отделна подписваща тайна на всяка крайна точка. Изчислете подписа след окончателното сериализиране JSON и изпратете точно тези байтове. Повторното сериализиране на обект след подписване може да промени празното пространство, екранирането или реда на свойствата и да обезсили проверката.

Получателите трябва да отхвърлят клеймото за време извън документирания толеранс, да изчисляват очаквания HMAC върху необработеното тяло и да сравняват подписите в постоянно време. След това те трябва да запазят идентификатора на събитието под уникално ограничение, преди да го потвърдят.

За ротация разрешете временно две активни тайни и включете подписи и от двете. Край на ротацията само след като партньорът потвърди новата тайна или след документиран период на припокриване. Никога не излагайте отново съществуваща тайна след първоначалното й създаване.

Направете всяка доставка видима и възпроизвеждана

Поддържайте всеки опит с неговия начален час, код на състоянието, латентност, категория на грешката, време за следващ повторен опит и извадка от отговор с ограничен размер. Редактирайте заглавките и телата на отговора преди показване. Операторите трябва да разграничават повреда на DNS, отказ на връзка, повреда на TLS, изчакване, отхвърляне HTTP и повреда на вътрешен работник.

Практична политика за отговор е:

• 200-299: маркирайте като доставено.
• 410: спрете доставката и деактивирайте крайната точка.
• 408, 425, 429 и 500-599: опитайте отново, спазвайки валидна стойност Retry-After в рамките на конфигурираните ограничения.
• Друго 400-499: класифициране като постоянна грешка на приемника и опитайте отново само според публикуваната политика.
• Грешки в мрежата и времето за изчакване: опитайте отново с експоненциално забавяне и трептене.

Ограничете паралелността за крайна точка, така че един повреден приемник да не може да използва работния пул. Разпределете повторните опити за няколко дни, предупреждавайте собствениците на крайни точки през отделен канал и деактивирайте крайна точка след документиран прозорец за грешка.

Ръчното повторение трябва да създаде нов опит за оригиналната двойка събитие-крайна точка. Не трябва да създава ново бизнес събитие, да променя event_id или да загатва, че основното действие се е случило отново.

Третирайте URL адресите за обратно извикване като SSRF граница

URL адрес за обратно извикване, контролиран от партньор, инструктира вашата инфраструктура къде да направи мрежова заявка. Това прави издателя на webhook цел на SSRF.

Препоръка: изисква HTTPS, ограничаване на портове, отхвърляне на вградени идентификационни данни и блокиране на дестинации за обратна връзка, частни, локални за връзки, групово предаване, резервирани и облачни метаданни. Разрешете името на хоста по време на проверката и отново при свързване. Проверете всеки разрешен адрес, не само първия.

Не следвай автоматично пренасочвания. Ако се поддържат пренасочвания, проверете всяко прескачане на дестинация и прилагайте малко ограничение за прескачане. Защитете срещу повторно обвързване на DNS, като се свържете само с валидирания публичен адрес, като запазите очакваното име на хост за TLS проверка.

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

Проектиране на потребители за дубликати и остарели събития

Получателят трябва да удостовери подписа, да потвърди клеймото за време и схемата, да вмъкне идентификатора на събитието в трайна входяща кутия, да постави обработката на опашка и да се върне бързо. Уникално ограничение за идентификатор на събитие превръща едновременните дубликати в нормален резултат от база данни.

Бизнес ефектите се нуждаят от собствен контрол на идемпотентността. Ако credit.adjustment_posted задейства счетоводно импортиране, въведете това импортиране в ИД на корекцията на източника, вместо да приемате, че дедупликацията на уеб кукичка защитава счетоводната книга. Времето за изчакване може да възникне, след като приемникът извърши своя ефект, но преди издателят да види отговора.

За променливо състояние, като например състояние на ключ, сравнете версиите на ресурса или извлечете текущото състояние, преди да приложите по-старо събитие. Това е особено важно за AI API бюджетни контроли, където забавено известие за праг не трябва да замества по-нов лимит или решение за прилагане.

Схеми на версиите и осигуряване на съгласуване

Схеми за уеб кукичка на версия независимо от нормалните отговори на партньор API. Поддържайте обратно съвместими допълнителни полета, публикувайте JSON схеми и примери и резервирайте нов тип събитие или URI на схема за несъвместима семантика. Закачете всяка крайна точка към изрично поведение на схема на събитие, вместо тихо да променяте полезните натоварвания, когато API се развива.

Уебкуките също се нуждаят от възстановяване, базирано на изтегляне:

• Списък на събития след курсор, обхванат от удостоверения партньор.
• Извличане на текущия клиент, ключ, баланс и състояние на бюджета.
• Експортиране на финализирано използване и корекции на счетоводната книга за период от време.
• Изложете ограниченията за задържане на доставката и прозореца за повторение.

Прогноза: партньорите в крайна сметка ще пропуснат известия поради изтекъл срок на задържане, деактивирани крайни точки, грешки при внедряването или продължителни прекъсвания. Емисия на събития, базирана на курсора, и API на авторитетното състояние превръщат този инцидент в работа по съгласуване вместо ръчно поправяне на данни.

Контролен списък за внедряване

• Семантика на събитието на документа, правила за пресичане и чувствителност на данните.
• Записвайте събития и достоверни промени в една транзакция.
• Налагане на партньорска собственост по време на разклоняване и доставка.
• Подписвайте стабилни идентификационни номера на събития, времеви клеймца на опити и необработени байтове за полезен товар.
• Съхранявайте доказателства за всеки опит и излагайте хронология на доставките с възможност за търсене.
• Поддръжка на припокриващи се тайни, тестови събития, деактивиране и повторно възпроизвеждане.
• Потвърдете дестинациите по време на регистрация и свързване.
• Тестови дубликати, доставка извън реда, изчакване след трайно получаване, припокриване на ротация, повторно обвързване на DNS, пренасочвания на частен IP, ограничаване на скоростта и продължителен престой.
• Наблюдавайте възрастта на изходящата кутия, дълбочината на опашката, степента на успех, деактивирането на крайната точка и насищането при повторен опит.
• Поддържайте достъпни API за съгласуване след изтичане на записите за доставка.

Създаване на известия около достоверни записи

Надеждният дизайн не е по-агресивен цикъл на повторен опит. Това е верига от трайни граници: ангажирано състояние, създаване на транзакционно събитие, разклонение с обхват на наемателя, подписана доставка, идемпотентно получаване и базирано на изтегляне съгласуване. Приложете тези граници, преди да разширите каталога на събитията. След това партньорите могат да автоматизират осигуряването, контролите на достъпа, балансите, бюджетите и използването, без да третират ненадежден HTTP обмен като система за запис.

Свързано четене

• проектиране на идемпотентен партньор API странични ефекти