Webhook events

Planned, outbound webhooks for customer events are not yet available. This documents the designed interface.

Outbound webhooks will let your systems react to events in your Topolab account, for example a dataset refresh completing or an invoice being paid, without polling. This page describes the planned model so you can design against it; endpoints and payloads may change before release.

Until then: poll for changes

There is no customer webhook API yet. To detect a dataset refresh today, poll the dataset metadata and watch its timestamps: compare dataRefreshedAt (and metadata.issued) from Get a dataset against the value you last saw, or check for a newer archive month. When the timestamp advances, the data has been refreshed. See Refresh hooks for the full interim approach.

Scope: customer-facing vs internal

Topolab already consumes inbound webhooks from providers such as Stripe, PayPal, and Mailgun. Those are internal to the platform, authenticated with provider-specific signing secrets, and are not customer-facing. Do not build against them.

The feature described here is outbound: Topolab delivers signed events to an endpoint that you register and control.

Planned model

1. Register an endpoint. You provide an HTTPS URL and select the event types you want. Topolab returns a signing secret, shown once.
2. Receive events. Topolab sends an HTTP POST with a JSON payload for each matching event.
3. Verify the signature. Each request carries a signature header computed over the raw body with your signing secret. Reject requests that do not verify.
4. Acknowledge. Respond 2xx promptly. Any other status (or a timeout) marks the delivery as failed.
5. Retries. Failed deliveries are retried with exponential backoff over a bounded window, then marked failed.

Endpoints will be HTTPS-only. Webhook subscriptions are expected to be organization-scoped, consistent with API keys and the rest of the account model.

Planned event types

Event	Fires when
dataset.refreshed	A dataset you have access to completes a scheduled or on-demand refresh.
invoice.paid	An organization invoice is marked paid.
invoice.payment_failed	A payment attempt on an invoice fails.
apikey.rotated	An API key in the organization is rotated.
apikey.revoked	An API key in the organization is revoked.

The dataset.refreshed event corresponds to the dataset refresh lifecycle described in Refresh hooks.

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

Field	Description
id	Unique event identifier; use it to deduplicate retries.
type	The event type from the table above.
createdAt	ISO 8601 time the event was generated.
organizationId	The organization the event belongs to.
data	Event-specific payload.

Planned delivery and verification

• Transport: HTTP POST, Content-Type: application/json, over HTTPS.
• Signature: a header signed over the raw request body with your endpoint's signing secret. Verify before trusting the payload.
• Idempotency: retries reuse the same event id; treat delivery as at-least-once and deduplicate.
• Acknowledgement: return 2xx quickly; do heavy work asynchronously.
• Retries: exponential backoff over a bounded window, then the delivery is marked failed.

Availability

This interface is not yet built. To register interest or be notified when outbound webhooks ship, contact us.

Related

• Refresh hooks, the dataset refresh lifecycle behind dataset.refreshed.
• Invoices, the billing documents behind invoice events.