Build Partner API Webhooks for AI API Resellers: Podpisani dogodki, Trajna dostava in Varno ponovno predvajanje

Izpraševanje partnerja API za vsako spremembo stanja, stranke, ključa, proračuna in uporabe ustvari neprijetno nadzorno zanko: pomembna dejanja pridejo z zamudo, nespremenjeni viri se večkrat pridobijo in sočasne posodobitve je mogoče opaziti v napačnem vrstnem redu. Odhodni webhooki zmanjšajo to zakasnitev, vendar le, če so zgrajeni kot trajen sistem obveščanja in ne kot HTTP povratni klic, dodan obdelovalcem zahtev.

Bistveno pravilo je preprosto: webhook poroča o prehodu stanja, ki je že bil aktiven. Ne ustvari prehoda, ne nadomesti glavne knjige ali postane verodostojen zapis. Ta razlika je pomembna, kadar lahko dogodek zamrzne dostop stranke, sproži kreditno dejanje ali vpliva na račun.

Najprej določite pogodbo o dobavi

Ugotovljeno dejstvo: običajne specifikacije webhookov in veliki založniki webhookov predvidevajo vsaj enkratno dostavo. Ponovni poskusi lahko povzročijo dvojnike, neodvisne pošiljke pa lahko prispejo v napačnem vrstnem redu.

Priporočilo: objavite naslednjo pogodbo, preden razkrijete upravljanje končne točke API:

• Vsak poslovni dogodek ima stabilen, nespremenljiv ID dogodka.
• Isti ID dogodka se ohrani pri samodejnih ponovnih poskusih in ročnih ponovitvah.
• Dostava je vsaj enkrat; dostava natanko enkrat ni obljubljena.
• Naročanje ni zagotovljeno med končnimi točkami ali vrstami dogodkov.
• Uspešen odziv pomeni, da je sprejemnik trajno sprejel dogodek, ni nujno, da je vse nadaljnje delo končano.
• Webhooki so obvestila; Partner API bere in izvozi glavne knjige ostanejo verodostojni.

Ta pogodba ustreza AI API platformi preprodajalcev, ker nadzor dostopa in finančni dogodki zahtevajo takojšnje obveščanje in zanesljivo obnovitveno pot.

Začnite z ozkim katalogom dogodkov

Ne spreminjajte vsake posodobitve baze podatkov v javni dogodek. Objavite prehode, na katere lahko partner ukrepa in jih natančno definira.

Dogodki praga potrebujejo eksplicitno pravilo prečkanja. Oddaj, ko je bila prejšnja vrednost pod 80 odstotki, nova vrednost pa je na primer enaka ali višja od 80 odstotkov, namesto oddajanja pri vsakem naslednjem zapisu uporabe. Določite, ali lahko razveljavitve ponovno oborožijo prag in ali lahko prilagoditve ustvarijo novo prečkanje.

Priporočilo: se izogibajte vnašanju polnih API ključev, poverilnic ponudnika, neobdelanih pozivov ali podrobnih dokazov o zlorabah v uporabnih vsebinah. Dajte prednost identifikatorjem virov in minimalnim posnetkom stanja. Prejemnik lahko uporabi partnerja API za pridobivanje občutljivih ali hitro spreminjajočih se podrobnosti.

Ustvarjanje dogodkov iz odobrenega stanja

Objava neposredno iz upravljalnika zahtev ustvari dve okni za napake. Povratni klic lahko uide, preden se izvede transakcija baze podatkov, ali pa se lahko transakcija izvrši, medtem ko proces ne uspe, preden pošlje povratni klic. Transakcijski odhodni predal zapre obe okni.

Transakcijsko zaporedje pošiljanja

1. Začnite transakcijo nadzorne ravnine ali glavne knjige.
2. Uporabi avtoritativno spremembo stanja.
3. Vstavite nespremenljiv dogodek v tabelo pošiljanja v isti transakciji.
4. Povezava enkrat.
5. Omogoči izdajatelju, da zahteva dodeljene vrstice pošiljanja.
6. Razrešite primerne končne točke z uporabo partnerskega obsega dogodka in naročniških filtrov.
7. Ustvarite en zapis o dostavi za vsak par dogodek-končna točka.

Edinstvena omejitev na (event_id, endpoint_id) preprečuje podvojeni razdelek, ko delavci znova poskusijo. Stanje objave v pošiljanju je treba posodobiti s semantiko primerjaj in nastavi ali zaklepanjem vrstic, da lahko več delavcev varno sodeluje.

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
)

Odpošlji dodaja zapisovanje v bazo podatkov, čiščenje in spremljanje zaostankov. Ti stroški so upravičeni, če imajo obvestila finančne posledice ali posledice za nadzor dostopa. Povratni klic po najboljših močeh je morda še vedno sprejemljiv za telemetrijo izdelkov za enkratno uporabo, vendar ne bi smel deliti trditev o zanesljivosti sistema webhook partnerja API.

Uporabite stabilno ovojnico dogodka

Identiteta poslovnega dogodka naj bo ločena od identitete poskusa dostave. Dogodek ostane enak, ko ga znova poskusite; sprememba časovnega žiga poskusa in zapisa dostave.

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

Za denar uporabite decimalne nize ali manjša cela števila. Dokumentirajte politiko valute, natančnosti in zaokroževanja. ID korelacije bi moral povezati dogodek z izvorno operacijo partnerja API ali knjižbo v knjigi, ne da bi postal identiteta dogodka.

Uveljavi varen za najemnika razpršilnik

Razrešite naročnine v obsegu partnerja dogodka, preden ustvarite obremenitev, specifično za končno točko. ID končne točke, ki ga posreduje sporočilo opravila ali čakalne vrste, ne sme zadostovati za odobritev dostave. Delavec mora končno točko naložiti s predikatom, enakovrednim endpoint.partner_id = event.partner_id, in preveriti, ali je aktivna in naročena na vrsto dogodka.

To je izhodna protipostavka avtorizaciji najemnika v Partner API avtomatizaciji: lastništvo objekta je treba znova vzpostaviti na vsaki asinhroni meji.

Podpiši točne bajte, ki jih pošiljaš

Ugotovljeno dejstvo: standardna specifikacija Webhooks definira glave webhook-id, webhook-timestamp in webhook-signature ter skupaj podpiše ID dogodka, časovni žig poskusa in neobdelano telo zahteve.

Dodelite ločeno skrivnost za podpisovanje vsaki končni točki. Izračunajte podpis po končni JSON serializaciji in pošljite točno tiste bajte. Ponovna serializacija predmeta po podpisovanju lahko spremeni presledke, ubežne znake ali vrstni red lastnosti in razveljavi preverjanje.

Prejemniki morajo zavrniti časovne žige zunaj dokumentirane tolerance, izračunati pričakovani HMAC v neobdelanem telesu in primerjati podpise v konstantnem času. Nato morajo ohraniti ID dogodka pod edinstveno omejitvijo, preden ga potrdijo.

Za rotacijo začasno dovolite dve aktivni skrivnosti in vključite podpisa obeh. Končajte rotacijo šele, ko partner potrdi novo skrivnost ali po dokumentiranem obdobju prekrivanja. Nikoli več ne razkrijte obstoječe skrivnosti po prvem ustvarjanju.

Naredite vsako dostavo opazljivo in ponovno predvajano

Obdrži vsak poskus z začetnim časom, statusno kodo, zakasnitvijo, kategorijo napake, časom naslednjega ponovnega poskusa in odlomkom odgovora z omejeno velikostjo. Uredite glave in telesa odgovorov pred prikazom. Operaterji morajo razlikovati med napako DNS, zavrnitvijo povezave, napako TLS, časovno omejitvijo, HTTP zavrnitvijo in notranjo napako delavca.

Praktični odzivni pravilnik je:

• 200-299: označi dostavljeno.
• 410: ustavite dostavo in onemogočite končno točko.
• 408, 425, 429 in 500-599: poskusite znova, pri čemer upoštevajte veljavno vrednost Retry-After znotraj konfiguriranih omejitev.
• Drugo 400-499: klasificirajte kot trajno napako sprejemnika in poskusite znova le v skladu z objavljenim pravilnikom.
• Napake omrežja in časovne omejitve: poskusite znova z eksponentnim odmikom in tresenjem.

Omejitev sočasnosti na končno točko, tako da en okvarjeni sprejemnik ne more porabiti skupine delavcev. Razporedite ponovne poskuse na več dni, opozorite lastnike končnih točk prek ločenega kanala in onemogočite končno točko po oknu dokumentirane napake.

Ročno ponovno predvajanje bi moralo ustvariti nov poskus za prvotni par dogodek-končna točka. Ne sme ustvariti novega poslovnega dogodka, spremeniti event_id ali namigovati, da se je temeljno dejanje ponovilo.

Obravnavajte povratne URL-je kot mejo SSRF

URL za povratni klic, ki ga nadzira partner, vaši infrastrukturi naroči, kam naj pošlje omrežno zahtevo. Zaradi tega je založnik webhook cilj SSRF.

Priporočilo: zahtevajte HTTPS, omejite vrata, zavrnite vdelane poverilnice in blokirajte cilje povratne zanke, zasebne, lokalne povezave, multicast, rezervirane in metapodatke v oblaku. Razrešite ime gostitelja med preverjanjem in znova pri povezovanju. Preverite vsak razrešen naslov, ne le prvega.

Ne sledi samodejno preusmeritvam. Če so preusmeritve podprte, potrdite vsak ciljni skok in uporabite majhno omejitev skoka. Zaščitite se pred ponovnim povezovanjem DNS tako, da se povežete samo s potrjenim javnim naslovom, medtem ko ohranite pričakovano ime gostitelja za preverjanje TLS.

Zagon dostavnikov v izoliranem omrežnem segmentu brez dostopa do baz podatkov nadzorne ravnine, notranjih skrbniških storitev, API-jev za orkestracijo ali metapodatkov primerkov. Uporabite omejitve telesa zahteve, omejitve velikosti odgovora, časovne omejitve povezave in skupne roke zahtev.

Načrtovanje porabnikov za dvojnike in zastarele dogodke

Prejemnik mora potrditi pristnost podpisa, potrditi časovni žig in shemo, vstaviti ID dogodka v trajno mapo »Prejeto«, obdelavo postaviti v čakalno vrsto in se hitro vrniti. Edinstvena omejitev ID-ja dogodka spremeni sočasne dvojnike v običajen rezultat baze podatkov.

Poslovni učinki potrebujejo lasten nadzor idempotence. Če credit.adjustment_posted sproži uvoz računovodstva, vnesite ta uvoz v ID izvorne prilagoditve, namesto da predvidevate, da samo deduplikacija webhooka ščiti glavno knjigo. Časovna omejitev lahko nastopi potem, ko prejemnik izvede svoj učinek, vendar preden izdajatelj vidi odgovor.

Za spremenljivo stanje, kot je stanje ključa, primerjajte različice vira ali pridobite trenutno stanje, preden uporabite starejši dogodek. To je še posebej pomembno za AI API nadzor proračuna, kjer odloženo obvestilo o pragu ne sme prepisati novejše omejitve ali odločitve o uveljavitvi.

Sheme različic in zagotavljanje usklajevanja

Različice shem webhook neodvisno od običajnih partnerskih API odgovorov. Ohranite združljivost aditivnih polj za nazaj, objavite JSON sheme in primere ter rezervirajte novo vrsto dogodka ali URI sheme za nezdružljivo semantiko. Pripnite vsako končno točko na eksplicitno vedenje sheme dogodka, namesto da tiho spreminjate obremenitve, ko se API razvije.

Webhooki potrebujejo tudi obnovitev na podlagi potezanja:

• Seznam dogodkov za kazalcem, v obsegu overjenega partnerja.
• Pridobite trenutno stranko, ključ, stanje in stanje proračuna.
• Izvoz končne uporabe in prilagoditev glavne knjige za določeno časovno obdobje.
• Izpostavite zadrževanje dostave in omejitve oken za ponovno predvajanje.

Predvidevanje: partnerji bodo sčasoma zamudili obvestila zaradi potekle hrambe, onemogočenih končnih točk, napak pri uvajanju ali dolgotrajnih izpadov. Vir dogodkov, ki temelji na kazalcu, in API-ji avtoritativnega stanja spremenijo ta incident v usklajevalno delo namesto ročnega popravljanja podatkov.

Kontrolni seznam za implementacijo

• Semantika dogodkov dokumenta, pravila križanja in občutljivost podatkov.
• Pisanje dogodkov in verodostojnih sprememb v eni transakciji.
• Uveljavite partnersko lastništvo med razpršitvijo in dostavo.
• Podpiši stabilne ID-je dogodkov, časovne žige poskusov in neobdelane bajte tovora.
• Shranite dokaze za vsak poskus in razkrijte zgodovino dostave, po kateri je mogoče iskati.
• Podpora za prekrivajoče se skrivnosti, preizkusne dogodke, onemogočanje in ponovno predvajanje.
• Potrdite cilje ob registraciji in času povezave.
• Testni dvojniki, dostava izven vrstnega reda, časovna omejitev po trajnem prejemu, prekrivanje rotacije, ponovno povezovanje DNS, preusmeritve zasebnega IP-ja, omejevanje hitrosti in podaljšani izpadi.
• Spremljajte starost pošiljanja, globino čakalne vrste, stopnjo uspešnosti, onemogočanje končne točke in nasičenost ponovnega poskusa.
• API-ji za usklajevanje naj bodo na voljo po poteku zapisov o dostavi.

Gradite obvestila okoli verodostojnih zapisov

Zanesljiva zasnova ni bolj agresivna ponovna zanka. To je veriga trajnih meja: predano stanje, ustvarjanje transakcijskega dogodka, razprševanje v obsegu najemnika, podpisana dostava, idempotentno potrdilo in usklajevanje na podlagi vlečenja. Izvedite te meje, preden razširite katalog dogodkov. Partnerji lahko nato avtomatizirajo zagotavljanje, nadzor dostopa, stanja, proračune in uporabo, ne da bi nezanesljivo HTTP izmenjavo obravnavali kot sistem zapisa.

Sorodno branje

• oblikovanje stranskih učinkov idempotentnega partnerja API