Register an endpoint

Registering a reporting endpoint is a Cockpit action, not a partner API call — the URL, the topics, the optional headers, and the signing secret you are shown once.
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.
Custom headers (optional)Extra headers sent on every delivery, e.g. a routing tag. Reserved headers like Content-Type cannot be overridden.

In return the endpoint gets a signing secret, shown once at creation. Store it where your receiver can read it, never commit it, and rotate it if it leaks. Every delivery is signed with it — 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.
  • Use a custom header as a routing tag if one receiver serves several tenants, and still read tenant_id from the envelope rather than trusting the tag alone.

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 delivery log for the endpoint when something looks wrong; every attempt is recorded, and a past event can be redelivered from there.
  • Watch for auto-disable. An endpoint that keeps failing is disabled so the platform stops sending to a dead URL, and it has to be re-enabled from Cockpit. An endpoint that silently stopped receiving events may have been disabled after a sustained outage — which, for a reporting pipeline, looks exactly like "the numbers stopped moving".

Both are covered in Delivery.

Where to go next

Was this page helpful?