Subscribing to Events

What a subscription is

A subscription is simply the configuration that tells a provider send these event types to this URL. Until you create one, the provider has no reason and no instruction to call you, so nothing arrives. Creating a subscription typically means registering an endpoint URL and then choosing which event types should trigger a delivery to it, so the provider knows both the where and the what.

You can usually have several subscriptions running at once — different URLs for different purposes within one application, or entirely separate ones for each environment you operate. Each subscription is an independent declaration of interest, and the provider will deliver any given event to every subscription whose filter happens to match it. That independence is what makes subscriptions flexible to organise around your real needs.

Subscribe to what you need

It is tempting to subscribe to absolutely everything so you never miss anything, but selecting only the event types you genuinely act on keeps the whole integration cleaner. Fewer event types means less traffic hitting your endpoint, less code to handle events you do not care about, and a smaller surface area to reason about when something goes wrong. Your receiver only ever sees the events it was actually built to handle.

That said, you should still design the receiver to ignore unrecognised types gracefully, since a provider may introduce new event types over time that match a broad subscription. Be deliberate about your initial selection and revisit it honestly as your integration grows and changes. The full catalogue of available event types you can choose from lives in the API documentation.

Subscriptions per environment

Keep your environments firmly separate at the subscription level. Your development, staging, and production systems should each have their own subscriptions pointing at their own distinct endpoints, so that a test event fired in staging never lands in production, and a real production event never wanders into a half-built test handler. Mixing them together is a reliable source of confusing, hard-to-trace behaviour that wastes hours.

Where a provider offers a dedicated test or sandbox mode, use it for all of your non-production subscriptions so the separation is enforced rather than merely intended. This isolation matters most of all when an event triggers a real side effect — you very much do not want a staging delivery sending an actual message to a real customer. The developer portal describes how to set up environments cleanly.

Managing subscriptions over time

Subscriptions are emphatically not set-and-forget configuration. As your endpoint URL changes between deploys, as you add new event types you want to react to, or as you retire features that produced events you no longer need, you will find yourself updating or removing subscriptions accordingly. Treat each of these changes carefully, because a misconfigured subscription silently stops events flowing — a failure that produces no error and is consequently very easy to miss entirely.

It is good practice to manage your subscriptions as code or version-controlled configuration, so that every change is reviewed and reproducible, rather than being clicked into a dashboard by hand and forgotten. Review the full set periodically against what your integration genuinely needs today, and prune anything that has quietly gone stale. A little hygiene here prevents a lot of confusion later.