Register an endpoint

Registering a reporting endpoint is a Cockpit action, not a partner API call — the URL, the topics, registered per tenant, and what Cockpit does not offer yet.
Registering an endpoint is a Cockpit action. Endpoints are managed for a tenant in Cockpit. There is nothing for you to call from your own code to create one, and no partner-facing API to enrol a reporting receiver programmatically.

That has a practical consequence for how you ship: an integration that needs a webhook endpoint needs somebody with Cockpit access to create it, once, per tenant. Put it in your onboarding checklist rather than your installer.

The full reference is Webhooks. This page is what to decide before you ask for one.

What you provide

You supplyDecide it as
URLAn HTTPS endpoint you control, that answers quickly with a 2xx.
TopicsExactly the topics you need — not everything.

In Cockpit this is Integration Studio → Webhooks → Outbound. Every delivery is signed, but Cockpit does not show the signing secret yet (as of 2026-09), so a receiver cannot verify one today. Until it can, treat each delivery as a notification and re-read the entity through the API before it reaches your figures — see Verify a delivery.

Deciding the URL

For a reporting receiver specifically:

  • One endpoint per purpose, not per topic. A single receiver that switches on topic is easier to keep idempotent than five receivers that each half-understand the stream.
  • Give it a path you can version. …/revenexx/v1 costs nothing now and saves a coordinated cutover later, since changing the URL means going back to Cockpit.
  • Make it dumb. Verify, dedupe, persist, return 2xx. Anything that computes or aggregates belongs behind a queue — a receiver that is slow because it is doing analytics work is a receiver that trips timeouts and gets retried.
  • Put the tenant in the path if one receiver serves several tenants, such as …/revenexx/v1/<tenant>. Endpoints are registered per tenant, and a delivery does not name its tenant, so the URL is the only place that says which tenant a delivery belongs to.

Choosing topics

Subscribe narrowly. You receive the topics you ask for and nothing else, and a narrow subscription is cheaper to make correct, cheaper to reason about, and quieter in your logs.

Adding a topic later means editing the endpoint in Cockpit — again a human step. It is worth thinking through the second and third figure you will be asked for before the first one ships.

After it exists

  • Check the endpoint's delivery attempts in Cockpit when something looks wrong. Each attempt shows when it ran, the topic, whether it succeeded and the HTTP status your receiver returned.
  • Nothing can be redelivered. An event whose attempts ran out, about 8.5 hours after the first, is not sent again. The recovery is an API re-read of the window you missed; see Incremental sync.
  • An endpoint is not switched off automatically, but anyone with Cockpit access can switch it off by hand, and events are dropped while it is off, not queued. For a reporting pipeline that looks exactly like "the numbers stopped moving", so check the switch before you debug the receiver, and re-read the gap from the API afterwards.

Both are covered in Delivery.

Where to go next

Was this page helpful?