Subscribe to webhook events

Planned: outbound customer webhooks are not yet available. This documents the designed interface so you can build against it; endpoints and payloads may change before release.

Outbound, not inbound

The feature described here is outbound: Topolab delivers signed events to an HTTPS endpoint you register and control. Topolab also consumes inbound webhooks from providers such as Stripe and Mailgun, but those are internal to the platform and not customer-facing — do not build against them.

The planned model

Register an HTTPS endpoint and select event types; Topolab returns a signing secret shown once. For each matching event Topolab sends an HTTP POST with a JSON payload and a signature header computed over the raw body — verify it before trusting the payload. Respond 2xx promptly; anything else (or a timeout) marks the delivery failed and it is retried with exponential backoff over a bounded window.

Planned event types include dataset.refreshed, invoice.paid, invoice.payment_failed, apikey.rotated, and apikey.revoked. Subscriptions are expected to be organization-scoped, consistent with the rest of the account model.

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

Tip · Deduplicate on the event id

Retries reuse the same event id, so treat delivery as at-least-once and deduplicate on that id. To register interest or be notified when outbound webhooks ship, contact us.