Webhook evenementen

Gepland — uitgaande webhooks voor klantevenementen zijn nog niet beschikbaar. Dit documenteert de ontworpen interface.

Uitgaande webhooks laten jouw systemen reageren op evenementen in jouw Topolab-account — bijvoorbeeld wanneer een datasetvernieuwing is voltooid of een factuur is betaald — zonder te polleren. Deze pagina beschrijft het geplande model zodat je hiertegen kunt ontwerpen; eindpunten en payloads kunnen veranderen voor de release.

Scope: klantgericht vs intern

Topolab consumeert al inkomende webhooks van aanbieders zoals Stripe, PayPal en Mailgun. Deze zijn intern voor het platform, geverifieerd met aanbieder-specifieke ondertekengeheimen, en zijn niet klantgericht. Bouw hier niet tegen.

De functie die hier wordt beschreven is uitgaand: Topolab levert ondertekende evenementen aan een eindpunt dat je registreert en beheert.

Gepland model

1. Registreer een eindpunt. Je biedt een HTTPS-URL en selecteert de evenementtypes die je wilt. Topolab retourneert een ondertekengeheim, dat één keer wordt getoond.
2. Ontvang evenementen. Topolab stuurt een HTTP POST met een JSON-payload voor elk bijpassend evenement.
3. Verifieer de handtekening. Elke aanvraag bevat een handtekeningheader die is berekend over de ruwe body met jouw ondertekengeheim. Weiger aanvragen die niet verifiëren.
4. Bevestig. Reageer snel met 2xx. Elke andere status (of een time-out) markeert de levering als mislukt.
5. Herhalingen. Mislukte leveringen worden opnieuw geprobeerd met exponentiële backoff over een begrensd venster, en worden daarna als mislukt gemarkeerd.

Eindpunten zullen alleen HTTPS zijn. Webhook-abonnementen worden verwacht organisatie-gebonden te zijn, in overeenstemming met API-sleutels en de rest van het accountmodel.

Geplande evenementtypes

Evenement	Vindt plaats wanneer
dataset.refreshed	Een dataset waar je toegang toe hebt voltooit een geplande of on-demand vernieuwing.
invoice.paid	Een organisatiefactuur wordt als betaald gemarkeerd.
invoice.payment_failed	Een betalingspoging op een factuur mislukt.
apikey.rotated	Een API-sleutel in de organisatie wordt gedraaid.
apikey.revoked	Een API-sleutel in de organisatie wordt ingetrokken.

Het dataset.refreshed evenement komt overeen met de levenscyclus van de datasetvernieuwing die wordt beschreven in Vernieuwingshooks.

Geplande payload

{
  "id": "evt_3f9a2c7e",
  "type": "invoice.paid",
  "createdAt": "2026-05-29T11:30:00Z",
  "organizationId": "org_8f3a2c7e",
  "data": {
    "invoiceId": "inv_7e8b1d40",
    "number": "2026-0042",
    "amountPaid": 49000,
    "currency": "EUR"
  }
}

Veld	Beschrijving
id	Unieke evenementidentificatie; gebruik het om herhalingen te dedupliceren.
type	Het evenementtype uit de bovenstaande tabel.
createdAt	ISO 8601 tijd waarop het evenement is gegenereerd.
organizationId	De organisatie waartoe het evenement behoort.
data	Evenement-specifieke payload.

Geplande levering en verificatie

• Transport: HTTP POST, Content-Type: application/json, over HTTPS.
• Handtekening: een header ondertekend over de ruwe aanvraagbody met jouw eindpunt's ondertekengeheim. Verifieer voordat je de payload vertrouwt.
• Idempotentie: herhalingen gebruiken dezelfde evenement id; behandel levering als ten minste eenmaal en deduplicate.
• Bevestiging: retourneer 2xx snel; doe zwaar werk asynchroon.
• Herhalingen: exponentiële backoff over een begrensd venster, daarna wordt de levering als mislukt gemarkeerd.

Beschikbaarheid

Deze interface is nog niet gebouwd. Om interesse te registreren of op de hoogte te worden gesteld wanneer uitgaande webhooks worden verzonden, neem contact met ons op.

Gerelateerd

• Vernieuwingshooks — de levenscyclus van de datasetvernieuwing achter dataset.refreshed.
• Facturen — de factureringsdocumenten achter factuurevenementen.