Bouw partner API webhooks voor AI API resellers: ondertekende evenementen, duurzame levering en veilige herhaling

Het ondervragen van een partner API voor elke wijziging in saldo, klant, sleutel, budget en gebruik creëert een lastige controlelus: belangrijke acties komen te laat, ongewijzigde bronnen worden herhaaldelijk opgehaald en gelijktijdige updates kunnen in de verkeerde volgorde worden waargenomen. Uitgaande webhooks verminderen die vertraging, maar alleen als ze zijn gebouwd als een duurzaam meldingssysteem in plaats van een HTTP callback toegevoegd aan verzoekafhandelaars.

De essentiële regel is simpel: een webhook rapporteert een statusovergang die al is doorgevoerd. Het creëert niet de overgang, vervangt het grootboek en wordt niet het gezaghebbende record. Dit onderscheid is van belang wanneer een gebeurtenis de toegang van klanten kan bevriezen, een kredietactie kan activeren of een factuur kan beïnvloeden.

Definieer eerst het leveringscontract

Vaststaand feit: algemene webhookspecificaties en grote webhookuitgevers gaan uit van minimaal één levering. Nieuwe pogingen kunnen duplicaten opleveren en onafhankelijke leveringen kunnen in de verkeerde volgorde aankomen.

Aanbeveling: publiceer het volgende contract voordat u een eindpuntbeheer openbaar maakt API:

• Elke zakelijke gebeurtenis heeft een stabiele, onveranderlijke gebeurtenis-ID.
• Dezelfde gebeurtenis-ID blijft behouden bij automatische nieuwe pogingen en handmatige herhalingen.
• De levering vindt minimaal één keer plaats; Levering in één keer wordt niet beloofd.
• Bestelling is niet gegarandeerd voor eindpunten of gebeurtenistypen.
• Een succesvol antwoord betekent dat de ontvanger de gebeurtenis duurzaam heeft geaccepteerd, en niet noodzakelijkerwijs dat al het verdere werk is voltooid.
• Webhooks zijn meldingen; Partner API leest en grootboekexports blijven gezaghebbend.

Dit contract past bij een AI API resellerplatform omdat toegangscontrole en financiële gebeurtenissen zowel snelle meldingen als een betrouwbaar herstelpad nodig hebben.

Begin met een beperkte evenementencatalogus

Maak van elke database-update niet een openbaar evenement. Publiceer transities waarop een partner actie kan ondernemen en die nauwkeurig kan worden gedefinieerd.

Drempelgebeurtenissen hebben een expliciete overschrijdingsregel nodig. Uitzenden wanneer de eerdere waarde lager dan 80 procent was en de nieuwe waarde bijvoorbeeld op of boven 80 procent ligt, in plaats van uit te zenden bij elk volgend gebruiksrecord. Bepaal of omkeringen de drempel kunnen herbewapenen en of aanpassingen een nieuwe overschrijding kunnen genereren.

Aanbeveling: vermijd het plaatsen van volledige API sleutels, providergegevens, onbewerkte aanwijzingen of gedetailleerd misbruikbewijs in payloads. Geef de voorkeur aan resource-ID's en minimale momentopnamen van de status. Een ontvanger kan de Partner API gebruiken om gevoelige of snel veranderende gegevens op te halen.

Gebeurtenissen maken vanuit vastgelegde status

Als u rechtstreeks vanuit een verzoekhandler publiceert, ontstaan er twee foutperioden. De callback kan ontsnappen voordat de databasetransactie wordt doorgevoerd, of de transactie kan worden vastgelegd terwijl het proces mislukt voordat de callback wordt verzonden. Een transactionele outbox sluit beide vensters.

Transactionele outbox-reeks

1. Begin de controlevlak- of grootboektransactie.
2. Pas de gezaghebbende statuswijziging toe.
3. Voeg een onveranderlijke gebeurtenis toe aan een outbox-tabel in dezelfde transactie.
4. Eenmalig vastleggen.
5. Laat een medewerker van een uitgever vastgelegde outbox-rijen claimen.
6. Los in aanmerking komende eindpunten op met behulp van de partnerbereik- en abonnementsfilters van het evenement.
7. Maak één leveringsrecord voor elk gebeurtenis-eindpuntpaar.

Een unieke beperking op (event_id, endpoint_id) voorkomt dubbele fanout wanneer werknemers het opnieuw proberen. De publicatiestatus van het Postvak IN moet worden bijgewerkt met semantiek voor vergelijken en instellen of rijvergrendeling, zodat meerdere medewerkers veilig kunnen samenwerken.

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
)

De outbox voegt databaseschrijfbewerkingen, opruimwerk en backlogmonitoring toe. Deze kosten zijn gerechtvaardigd wanneer meldingen financiële of toegangscontroleconsequenties hebben. Een best-effort callback kan nog steeds acceptabel zijn voor telemetrie van wegwerpproducten, maar mag niet de betrouwbaarheidsclaims van het Partner API webhooksysteem delen.

Gebruik een stabiele gebeurtenisenvelop

Houd de identiteit van het zakelijke evenement gescheiden van de identiteit van de bezorgpoging. De gebeurtenis blijft hetzelfde wanneer deze opnieuw wordt geprobeerd; de tijdstempel van de poging en de leveringsrecord veranderen.

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

Gebruik decimale tekenreeksen of gehele getallen van kleine eenheden voor geld. Documenteer het valuta-, precisie- en afrondingsbeleid. De correlatie-ID moet de gebeurtenis verbinden met de oorspronkelijke Partner API-bewerking of grootboekboeking zonder de identiteit van de gebeurtenis te worden.

Tenantveilige fanout afdwingen

Los abonnementen op binnen het partnerbereik van het evenement voordat u eindpuntspecifieke payloads samenstelt. Een eindpunt-ID die door een taak- of wachtrijbericht wordt verstrekt, mag niet voldoende zijn om de bezorging te autoriseren. De werker moet het eindpunt laden met een predikaat dat equivalent is aan endpoint.partner_id = event.partner_id en verifiëren dat het actief is en geabonneerd is op het gebeurtenistype.

Dit is de uitgaande tegenhanger van tenantautorisatie in Partner API automatisering: het objecteigendom moet opnieuw worden ingesteld bij elke asynchrone grens.

Onderteken de exacte bytes die u verzend

Vaststaand feit: de standaardwebhooks-specificatie definieert webhook-id, webhook-timestamp en webhook-signature headers en ondertekent de gebeurtenis-ID, de tijdstempel van de poging en de onbewerkte verzoektekst samen.

Wijs een duidelijk ondertekeningsgeheim toe aan elk eindpunt. Bereken de handtekening na de laatste JSON-serialisatie en verzend de exacte bytes. Het opnieuw serialiseren van een object na ondertekening kan de witruimte, escape-tekens of eigenschapsvolgorde veranderen en de verificatie ongeldig maken.

Ontvangers moeten tijdstempels buiten een gedocumenteerde tolerantie afwijzen, de verwachte HMAC over de ruwe inhoud berekenen en handtekeningen in constante tijd vergelijken. Vervolgens moeten ze de gebeurtenis-ID onder een unieke beperking bewaren voordat ze deze erkennen.

Voor rotatie: sta tijdelijk twee actieve geheimen toe en voeg handtekeningen van beide toe. Beëindig de rotatie pas nadat de partner het nieuwe geheim heeft bevestigd of na een gedocumenteerde overlapperiode. Geef nooit meer een bestaand geheim prijs nadat het voor het eerst is gemaakt.

Maak elke levering waarneembaar en herspeelbaar

Houd elke poging vol met de starttijd, statuscode, latentie, foutcategorie, tijd voor de volgende nieuwe poging en een reactiefragment met een beperkte grootte. Redig kopteksten en antwoordteksten voordat ze worden weergegeven. Operators moeten onderscheid maken tussen DNS-fout, verbindingsweigering, TLS-fout, time-out, HTTP afwijzing en interne werkerfout.

Een praktisch reactiebeleid is:

• 200-299: markeer afgeleverd.
• 410: stop de levering en schakel het eindpunt uit.
• 408, 425, 429 en 500-599: probeer het opnieuw en respecteer een geldige Retry-After-waarde binnen de geconfigureerde limieten.
• Overig 400-499: classificeer als een aanhoudende ontvangerfout en probeer het alleen opnieuw volgens het gepubliceerde beleid.
• Netwerk- en time-outfouten: probeer het opnieuw met exponentiële uitstel en jitter.

Beperk de gelijktijdigheid per eindpunt, zodat één falende ontvanger de werkrollenpool niet kan gebruiken. Spreid nieuwe pogingen over meerdere dagen, waarschuw eindpunteigenaren via een apart kanaal en schakel een eindpunt uit na een gedocumenteerde foutperiode.

Handmatig afspelen zou een nieuwe poging moeten creëren voor het oorspronkelijke gebeurtenis-eindpuntpaar. Het mag geen nieuwe zakelijke gebeurtenis creëren, event_id wijzigen of impliceren dat de onderliggende actie opnieuw heeft plaatsgevonden.

Behandel callback-URL's als een SSRF-grens

Een door een partner beheerde callback-URL geeft uw infrastructuur instructies waar een netwerkverzoek moet worden ingediend. Dat maakt de webhookuitgever tot een SSRF-doel.

Aanbeveling: vereist HTTPS, beperk poorten, wijs ingebedde inloggegevens af en blokkeer loopback-, privé-, link-local-, multicast-, gereserveerde en cloud-metagegevensbestemmingen. Los de hostnaam op tijdens de validatie en opnieuw bij het verbinden. Verifieer elk opgelost adres, niet alleen het eerste.

Volg omleidingen niet automatisch. Als omleidingen worden ondersteund, valideer dan elke bestemmingshop en pas een kleine hoplimiet toe. Bescherm tegen DNS-rebinding door alleen verbinding te maken met het gevalideerde openbare adres, terwijl de verwachte hostnaam voor TLS-verificatie behouden blijft.

Voer bezorgingswerkers uit in een geïsoleerd netwerksegment zonder toegang tot databases op het controlevlak, interne beheerservices, orkestratie-API's of metadata van instanties. Pas limieten voor de hoofdtekst van verzoeken, limieten voor de reactiegrootte, verbindingstime-outs en totale verzoekdeadlines toe.

Ontwerp consumenten voor duplicaten en verouderde evenementen

De ontvanger moet de handtekening verifiëren, het tijdstempel en het schema valideren, de gebeurtenis-ID in een duurzame inbox invoegen, de verwerking in de wachtrij plaatsen en snel terugkeren. Een unieke gebeurtenis-ID-beperking verandert gelijktijdige duplicaten in een normaal databaseresultaat.

Bedrijfseffecten hebben hun eigen idempotentiecontroles nodig. Als credit.adjustment_posted een boekhoudimport activeert, sleutelt u die import aan de bronaanpassings-ID in plaats van aan te nemen dat alleen deduplicatie van de webhook het grootboek beschermt. Er kan een time-out optreden nadat de ontvanger zijn effect heeft vastgelegd, maar voordat de uitgever het antwoord ziet.

Voor een veranderlijke status, zoals de sleutelstatus, vergelijkt u bronversies of haalt u de huidige status op voordat u een oudere gebeurtenis toepast. Dit is vooral belangrijk voor AI API budgetcontroles, waarbij een melding van een vertraagde drempel een nieuwere limiet of handhavingsbeslissing niet mag overschrijven.

Versieschema's en afstemming bieden

Versie webhookschema's onafhankelijk van normale Partner API-reacties. Houd additieve velden achterwaarts compatibel, publiceer JSON schema's en voorbeelden en reserveer een nieuw gebeurtenistype of schema-URI voor incompatibele semantiek. Maak elk eindpunt vast aan een expliciet gebeurtenisschema-gedrag in plaats van stilzwijgend de payloads te wijzigen wanneer de API evolueert.

Webhooks hebben ook pull-gebaseerd herstel nodig:

• Gebeurtenissen weergeven na een cursor, gericht op de geverifieerde partner.
• Haal de huidige klant-, sleutel-, saldo- en budgetstatus op.
• Exporteer het definitieve gebruik en de grootboekaanpassingen voor een bepaalde periode.
• Maak de limieten voor bezorgingsretentie en herhalingsperiode zichtbaar.

Voorspelling: partners zullen uiteindelijk meldingen missen vanwege verlopen retentie, uitgeschakelde eindpunten, implementatiefouten of langdurige storingen. Een op cursor gebaseerde gebeurtenisfeed en gezaghebbende status-API's zetten dat incident om in afstemmingswerk in plaats van handmatig gegevensherstel.

Implementatiechecklist

• Documenteer de semantiek van gebeurtenissen, het overschrijden van regels en gegevensgevoeligheid.
• Schrijf gebeurtenissen en gezaghebbende wijzigingen in één transactie.
• Dwing partnereigendom af tijdens fanout en levering.
• Onderteken stabiele gebeurtenis-ID's, probeer tijdstempels en ruwe payload-bytes.
• Bewijs per poging opslaan en doorzoekbare leveringsgeschiedenis weergeven.
• Ondersteuning van overlappende geheimen, testgebeurtenissen, uitschakelen en opnieuw afspelen.
• Bestemmingen valideren bij registratie en verbindingstijd.
• Testduplicaten, levering buiten de bestelling, time-out na duurzame ontvangst, rotatie-overlapping, DNS-rebinding, privé-IP-omleidingen, snelheidsbeperking en langdurige downtime.
• Bewaak de leeftijd van het postvak, de diepte van de wachtrij, het slagingspercentage, het uitschakelen van eindpunten en de verzadiging van nieuwe pogingen.
• Houd afstemmings-API's beschikbaar nadat de leveringsgegevens verlopen.

Meldingen opbouwen rond gezaghebbende records

Het betrouwbare ontwerp is geen agressievere pogingslus. Het is een keten van duurzame grenzen: vastgelegde status, creatie van transactionele gebeurtenissen, fan-out op huurderbasis, ondertekende levering, idempotente ontvangst en op pull gebaseerde afstemming. Implementeer deze grenzen voordat u de evenementencatalogus uitbreidt. Partners kunnen vervolgens de levering, toegangscontrole, saldi, budgetten en gebruik automatiseren zonder een onbetrouwbare HTTP uitwisseling als het geregistreerde systeem te behandelen.

Gerelateerd lezen

• het ontwerpen van idempotente Partner API bijwerkingen