Event Types and Schemas

Types and schemas defined

An event type is a name for a particular kind of occurrence — something like resource.created or resource.updated that tells you, at a glance, what just happened. A schema is the structure of the payload that accompanies that type: which fields are present, what they are named, and what each of them means. Taken together, the type and its schema form the contract that a consumer writes its code against.

The type lets your receiver route an incoming event to the correct handler, while the schema tells that handler precisely what data it can expect to find inside. A provider publishes both halves of this contract — usually as a catalogue of available types, each documented with its own payload shape — so that consumers know exactly what they will receive before they ever receive it, and can build with confidence.

Relying on the catalogue

The provider's event catalogue is your single source of reference, and you should treat it as such. It lists every event type you are able to subscribe to and the schema that each one carries when it is delivered. Building your integration against the documented catalogue, rather than reverse-engineering from a single payload you happened to observe once, keeps your code correct and prevents the unpleasant surprises that come from assumptions.

In your handler, route on the type field and dispatch to a dedicated handler for each type you care about. For any type you have not built a handler for, ignore it gracefully and acknowledge it anyway. The authoritative, up-to-date list of every type and its schema is published in the API documentation, and that catalogue should be what drives the shape of your routing code.

Schemas evolve

Schemas inevitably change over time as a product grows and gains new capabilities. Providers generally evolve them additively — introducing new fields and new event types, while carefully avoiding the removal or repurposing of existing ones, precisely because those kinds of change break consumers who were depending on the old shape. Your job as a consumer is to be tolerant of that ongoing, additive growth.

// tolerant parsing: read what you need, ignore the rest
const { id, type, data } = event;
const handler = handlers[type] ?? ignore;
handler(data);

Reading only the specific fields you actually use, and quietly ignoring any unknown ones, means that newly added fields can never break your integration. This forward-compatible habit is closely tied to the advice in webhook payload design on the producing side.

Validate what arrives

Before you act on any event, check that it genuinely matches the schema you expect — that the required fields are present and that they hold values of the right type. Validation catches malformed or unexpected payloads early, right at the boundary, before they have a chance to cause a far more confusing failure deep inside your business logic. A clear, explicit rejection at the door always beats a cryptic downstream error three layers in.

The trick is to strike a sensible balance in how strict you are. Validate the fields you actually depend on strictly and reject anything missing them, but stay deliberately lenient about extra fields you do not use, so that the provider's additive changes never trip your validator unnecessarily. This validation pairs naturally with the signature verification covered in securing your endpoint against forged or tampered input.