Skip to main content

Endpoints and Accounts

Two terms matter on this page:

  • URL: the address of your receiver, the application that accepts the HTTP POST requests. You can register the same URL on as many Trackunit accounts as you like.
  • Endpoint: one registration of a URL on one Trackunit account, with its own event filter and signing secret. You create it on the account you are signed in to under Administration → Webhooks, and it delivers the events published to that account.

Events are published per account, and an endpoint delivers its own account's events. To receive events from several accounts, register the same URL as an endpoint on each of them. One receiver then handles all of them.

How an event reaches an endpoint​

  1. Something happens to an asset, for example a fault turns on, the asset enters a site, or its service status changes.
  2. Trackunit publishes a webhook event for each account the change concerns. Every copy is a separate event: it carries that account's id in the accountId field of the payload and has its own eventId.
  3. On each of those accounts, the event is delivered to every endpoint whose event filter includes the event type.

Delivery is decided account by account. An endpoint receives the events published for its account, and nothing else. Which accounts an event is published for is defined per event type and can differ between them. The Event Catalog lists the event types.

Parent accounts and sub-accounts​

Accounts form a hierarchy, but endpoints are not inherited along it:

  • An endpoint on a parent account does not receive events published for its sub-accounts.
  • An endpoint on a sub-account does not receive events published for the parent account.

For example, an organization has the parent account Acme with the sub-accounts Acme North and Acme South. An event published for Acme North is delivered to the endpoints of Acme North only. An endpoint on Acme never sees it, even though Acme is the parent.

Receiving events for a sub-account​

Add an endpoint on the sub-account itself:

  1. Sign in to the sub-account as an administrator, either with an administrator user of the sub-account or by impersonating one from the parent account under Administration → Accounts. Impersonating requires permission to log in to sub-accounts.
  2. Go to Administration → Webhooks and add the endpoint. Webhooks are enabled per account as part of IrisX, so the sub-account needs them too.
  3. Repeat for every sub-account whose events you want, using the same URL each time, see One URL for all your accounts.

One URL for all your accounts​

You do not need a receiver per account. Register the same URL as an endpoint on every account and one implementation handles all of them: the payload has the same shape for every account, and the accountId field says which account an event was published for.

What that one implementation has to do:

  • Select the signing secret by account. Each endpoint has its own secret. Read accountId from the body to pick the secret for that account, then verify the signature before acting on the event. Keep the raw request body for verification, since the signature covers the exact bytes, and reject events whose accountId you do not know. A delivery can carry more than one signature, for example while a secret is being rotated; the Svix libraries handle that. See Securing Webhooks.
  • Expect one delivery per account. A change that concerns several of your accounts produces one event per account, each with its own eventId.

What stays per account:

  • The endpoint has to be created on every account, each with the same event filter. See Receiving events for a sub-account.
  • Rate limit, retry schedule, replays and the delivery log belong to the endpoint. When troubleshooting, look at the account that owns the endpoint.

Not receiving events?​

  • Check which account the endpoint was created on. An endpoint is only listed under Administration → Webhooks of the account that owns it.
  • Check that the event concerns that account. Events are published per account, and an endpoint only receives the events published for its own account.
  • Check that webhooks are enabled on that account. Webhooks are part of IrisX and enabled per account; creating an endpoint does not check this, and events for an account without webhooks are dropped without an error.
  • Check that the endpoint's event filter is empty or includes the event type.
  • Check the endpoint's Attempted Messages for delivery attempts. See Testing Events.