Build Partner API Webhooks za AI API Resellers: potpisani događaji, dugotrajna isporuka i sigurno ponavljanje

Prozivanje partnera API za svaku promjenu stanja, klijenta, ključa, proračuna i upotrebe stvara neugodnu kontrolnu petlju: važne radnje kasne, nepromijenjeni resursi dohvaćaju se više puta, a istodobna ažuriranja mogu se promatrati pogrešnim redoslijedom. Izlazni web-dojavnici smanjuju to kašnjenje, ali samo ako su izgrađeni kao trajni sustav obavijesti, a ne HTTP povratni poziv dodan rukovateljima zahtjevima.

Osnovno pravilo je jednostavno: web-dojavnik prijavljuje prijelaz stanja koji je već izvršen. Ne stvara prijelaz, ne zamjenjuje glavnu knjigu niti postaje mjerodavni zapis. Ova razlika je važna kada događaj može zamrznuti pristup klijentu, pokrenuti kreditnu radnju ili utjecati na fakturu.

Prvo definirajte ugovor o isporuci

Utvrđena činjenica: uobičajene specifikacije web-dojavnika i veliki izdavači web-dojavnika pretpostavljaju isporuku barem jednom. Ponovni pokušaji mogu proizvesti duplikate, a neovisne isporuke mogu stići bez reda.

Preporuka: objavite sljedeći ugovor prije izlaganja upravljanja krajnjom točkom API:

• Svaki poslovni događaj ima stabilan, nepromjenjiv ID događaja.
• Isti ID događaja zadržava se tijekom automatskih ponovnih pokušaja i ručnih ponavljanja.
• Isporuka je najmanje jednom; isporuka točno jednom nije obećana.
• Redoslijed nije zajamčen preko krajnjih točaka ili vrsta događaja.
• Uspješan odgovor znači da je primatelj trajno prihvatio događaj, a ne nužno da je sav nizvodni rad završen.
• Webdojavljivači su obavijesti; Partner API čita i izvozi glavne knjige ostaju mjerodavni.

Ovaj ugovor odgovara AI API platformi preprodavača jer kontrola pristupa i financijski događaji zahtijevaju i brzu obavijest i pouzdan put oporavka.

Počnite s uskim katalogom događaja

Ne pretvarajte svako ažuriranje baze podataka u javni događaj. Objavite prijelaze na koje partner može djelovati i precizno definirati.

Događaji praga trebaju eksplicitno pravilo prijelaza. Emitiraj kada je prethodna vrijednost bila ispod 80 posto, a nova vrijednost je na ili iznad 80 posto, na primjer, umjesto emitiranja na svakom sljedećem zapisu upotrebe. Definirajte mogu li poništenja ponovno aktivirati prag i mogu li prilagodbe generirati novi prijelaz.

Preporuka: izbjegavajte stavljanje potpunih API ključeva, vjerodajnica pružatelja usluga, neobrađenih upita ili detaljnih dokaza o zlouporabi u korisnim sadržajima. Preferirajte identifikatore resursa i minimalne snimke stanja. Primatelj može koristiti Partner API za dohvaćanje osjetljivih ili brzo promjenjivih detalja.

Stvorite događaje iz predanog stanja

Objavljivanje izravno iz rukovatelja zahtjevima stvara dva prozora neuspjeha. Povratni poziv može pobjeći prije nego što se izvrši transakcija baze podataka ili se transakcija može izvršiti dok proces ne uspije prije slanja povratnog poziva. Transakcijski izlazni spremnik zatvara oba prozora.

Transakcijski odlazni redoslijed

1. Započnite transakciju kontrolne razine ili glavne knjige.
2. Primijenite mjerodavnu promjenu stanja.
3. Umetnite nepromjenjivi događaj u tablicu izlazne pošte u istoj transakciji.
4. Obvezati jednom.
5. Neka radnik izdavača zatraži predane redove izlazne pošte.
6. Razriješite krajnje točke koje ispunjavaju uvjete pomoću filtara partnerskog opsega događaja i pretplate.
7. Stvorite jedan zapis isporuke za svaki par događaja i krajnje točke.

Jedinstveno ograničenje na (event_id, endpoint_id) sprječava dvostruki fanout kada radnici pokušaju ponovno. Status objave izlazne pošte trebao bi se ažurirati semantikom usporedi i postavi ili zaključavanjem reda kako bi više radnika moglo sigurno surađivati.

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
)

Odlazna pošta dodaje pisanje baze podataka, rad na čišćenju i praćenje zaostataka. Ti su troškovi opravdani kada obavijesti imaju financijske posljedice ili posljedice za kontrolu pristupa. Povratni poziv najboljeg pokušaja još uvijek može biti prihvatljiv za telemetriju proizvoda za jednokratnu upotrebu, ali ne bi trebao dijeliti tvrdnje o pouzdanosti partnera API webhook sustava.

Koristite stabilnu omotnicu događaja

Odvojite identitet poslovnog događaja od identiteta pokušaja isporuke. Događaj ostaje isti kada se ponovno pokuša; vremenska oznaka pokušaja i promjena zapisa isporuke.

{
  "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"
  }
}

Koristite decimalne nizove ili manje-jediničke cijele brojeve za novac. Dokumentirajte politiku valute, preciznosti i zaokruživanja. ID korelacije trebao bi povezati događaj s operacijom izvornog partnera API ili knjiženjem u glavnoj knjizi, a da ne postane identitet događaja.

Nametnite sigurnu nadogradnju za stanara

Razriješite pretplate unutar partnerskog opsega događaja prije konstruiranja korisnih opterećenja specifičnih za krajnju točku. ID krajnje točke koji daje poruka o poslu ili redu čekanja ne smije biti dovoljan za autorizaciju isporuke. Radnik bi trebao učitati krajnju točku s predikatom ekvivalentnim endpoint.partner_id = event.partner_id i potvrditi da je aktivan i pretplaćen na vrstu događaja.

Ovo je izlazni pandan autorizaciji stanara u Partner API automatizaciji: vlasništvo nad objektom mora se ponovno uspostaviti na svakoj asinkronoj granici.

Potpišite točne bajtove koje šaljete

Utvrđena činjenica: specifikacija Standard Webhooks definira webhook-id, webhook-timestamp i webhook-signature zaglavlja i zajedno potpisuje ID događaja, vremensku oznaku pokušaja i neobrađeno tijelo zahtjeva.

Dodijelite posebnu tajnu potpisivanja svakoj krajnjoj točki. Izračunajte potpis nakon konačne JSON serijalizacije i pošaljite točne bajtove. Ponovna serijalizacija objekta nakon potpisivanja može promijeniti razmak, izlaz ili poredak svojstava i poništiti potvrdu.

Primatelji bi trebali odbiti vremenske oznake izvan dokumentirane tolerancije, izračunati očekivani HMAC preko neobrađenog tijela i usporediti potpise u konstantnom vremenu. Zatim bi trebali zadržati ID događaja pod jedinstvenim ograničenjem prije nego što ga potvrde.

Za rotaciju, privremeno dopustite dvije aktivne tajne i uključite potpise iz obje. Prekinite rotaciju tek nakon što partner potvrdi novu tajnu ili nakon dokumentiranog razdoblja preklapanja. Nikada više ne otkrivajte postojeću tajnu nakon početnog stvaranja.

Učinite svaku isporuku vidljivom i ponovnom

Ustrajte u svakom pokušaju s njegovim vremenom početka, statusnim kodom, kašnjenjem, kategorijom pogreške, sljedećim vremenom ponovnog pokušaja i izvatkom odgovora ograničenom veličinom. Uredite zaglavlja i tijela odgovora prije prikaza. Operateri moraju razlikovati grešku DNS-a, odbijanje veze, grešku TLS-a, vremensko ograničenje, HTTP odbijanje i internu grešku radnika.

Praktična politika odgovora je:

• 200-299: označiti isporučenim.
• 410: zaustavi isporuku i onemogući krajnju točku.
• 408, 425, 429 i 500-599: pokušajte ponovno, poštujući valjanu vrijednost Retry-After unutar konfiguriranih ograničenja.
• Drugo 400-499: klasificirajte kao stalnu pogrešku prijemnika i pokušajte ponovno samo prema objavljenim pravilima.
• Kvarovi mreže i vremenskog ograničenja: pokušajte ponovno s eksponencijalnim odmakom i podrhtavanjem.

Ograničite konkurentnost po krajnjoj točki tako da jedan neispravni prijamnik ne može iskoristiti skup radnika. Rasporedite ponovne pokušaje na više dana, upozorite vlasnike krajnjih točaka putem zasebnog kanala i onemogućite krajnju točku nakon dokumentiranog prozora neuspjeha.

Ručna reprodukcija trebala bi stvoriti novi pokušaj za izvorni par događaja i krajnje točke. Ne smije stvoriti novi poslovni događaj, promijeniti event_id ili implicirati da se temeljna radnja ponovila.

Tretirajte URL povratne pozive kao SSRF granicu

URL za povratni poziv kojim upravlja partner daje upute vašoj infrastrukturi gdje uputiti mrežni zahtjev. To izdavača webdojavnika čini SSRF metom.

Preporuka: zahtijevajte HTTPS, ograničite priključke, odbacite ugrađene vjerodajnice i blokirajte povratna petlja, privatna, lokalna veza, multicast, rezervirana i odredišta metapodataka u oblaku. Razriješite naziv glavnog računala tijekom provjere valjanosti i ponovno prilikom povezivanja. Provjerite svaku riješenu adresu, ne samo prvu.

Nemoj automatski slijediti preusmjeravanja. Ako su preusmjeravanja podržana, potvrdite svaki odredišni skok i primijenite malo ograničenje skoka. Zaštitite se od ponovnog povezivanja DNS-a povezivanjem samo s potvrđenom javnom adresom uz očuvanje očekivanog naziva glavnog računala za TLS provjeru.

Pokretanje isporučitelja u izoliranom mrežnom segmentu bez pristupa bazama podataka kontrolne razine, internim administratorskim uslugama, API-jima za orkestraciju ili metapodacima instance. Primijenite ograničenja tijela zahtjeva, ograničenja veličine odgovora, isteka vremena veze i ukupne rokove zahtjeva.

Potrošači dizajna za duplikate i zastarjele događaje

Primatelj bi trebao potvrditi autentičnost potpisa, potvrditi vremensku oznaku i shemu, umetnuti ID događaja u trajnu ulaznu poštu, staviti obradu u red i brzo se vratiti. Jedinstveno ograničenje ID-a događaja pretvara istodobne duplikate u normalan ishod baze podataka.

Poslovni efekti trebaju vlastite kontrole idempotencije. Ako credit.adjustment_posted pokrene računovodstveni uvoz, unesite taj uvoz u izvorni ID prilagodbe umjesto da pretpostavite da deduplikacija web-dojavnika sama štiti glavnu knjigu. Istek vremena može nastupiti nakon što primatelj izvrši svoj učinak, ali prije nego što izdavač vidi odgovor.

Za promjenjivo stanje kao što je status ključa, usporedite verzije resursa ili dohvatite trenutno stanje prije primjene starijeg događaja. Ovo je posebno važno za AI API kontrole proračuna, gdje odgođena obavijest o pragu ne smije prebrisati novije ograničenje ili odluku o provedbi.

Sheme verzija i pružanje usklađivanja

Sheme web-dojavnika verzije neovisno o normalnim odgovorima partnera API. Neka dodatna polja budu kompatibilna s prethodnim verzijama, objavite JSON sheme i primjere i rezervirajte novu vrstu događaja ili URI sheme za nekompatibilnu semantiku. Prikvačite svaku krajnju točku na eksplicitno ponašanje sheme događaja umjesto da tiho mijenjate korisna opterećenja kad god API evoluira.

Web-dojavnici također trebaju oporavak temeljen na povlačenju:

• Popis događaja nakon pokazivača, u rasponu do autentificiranog partnera.
• Dohvaćanje trenutnog klijenta, ključa, stanja i stanja proračuna.
• Izvoz finaliziranog korištenja i prilagodbi glavne knjige za određeni vremenski raspon.
• Izložite zadržavanje isporuke i ograničenja prozora za ponovnu reprodukciju.

Predviđanje: partneri će na kraju propustiti obavijesti zbog isteka zadržavanja, onemogućenih krajnjih točaka, pogrešaka u implementaciji ili produljenih prekida rada. Feed događaja temeljen na pokazivaču i API-ji ovlaštenog stanja pretvaraju taj incident u rad na usklađivanju umjesto ručnog popravka podataka.

Popis za provjeru implementacije

• Semantika događaja dokumenta, pravila križanja i osjetljivost podataka.
• Pišite događaje i mjerodavne promjene u jednoj transakciji.
• Nametnite partnersko vlasništvo tijekom fanouta i isporuke.
• Potpišite stabilne ID-ove događaja, vremenske oznake pokušaja i neobrađene bajtove korisnih podataka.
• Pohranite dokaze za svaki pokušaj i izložite pretraživu povijest isporuke.
• Podržava preklapajuće tajne, testne događaje, onemogućavanje i ponovnu reprodukciju.
• Potvrdite odredišta prilikom registracije i povezivanja.
• Testni duplikati, isporuka izvan redoslijeda, vremensko ograničenje nakon trajnog prijema, preklapanje rotacije, ponovno povezivanje DNS-a, preusmjeravanja privatnog IP-a, ograničenje brzine i produženi prekid rada.
• Nadzirite starost izlazne pošte, dubinu reda čekanja, stopu uspješnosti, onemogućavanje krajnje točke i zasićenje ponovnog pokušaja.
• Održavanje API-ja za usklađivanje dostupnima nakon isteka evidencije isporuke.

Izradite obavijesti oko vjerodostojnih zapisa

Pouzdan dizajn nije agresivnija petlja ponovnog pokušaja. To je lanac trajnih granica: predano stanje, stvaranje transakcijskog događaja, fanout s opsegom stanara, potpisana isporuka, idempotentna potvrda i usklađivanje temeljeno na povlačenju. Implementirajte te granice prije proširenja kataloga događaja. Partneri tada mogu automatizirati pružanje usluga, kontrole pristupa, stanja, proračune i korištenje bez tretiranja nepouzdane HTTP razmjene kao sustava evidencije.

Povezano čitanje

• dizajniranje idempotentnog partnera API nuspojave