Guides
Event Schemas
Attach a JSON Schema to an Event Type so a malformed payload is rejected at publish time — before it's ever written or delivered — instead of being discovered by a subscriber later.
Lifecycle
Every schema version moves through four states. Only one version can be active per Event Type at a time — enforced at the database level, not just in application code.
draft
→
active
→
deprecated
→
sunset
How validation works
Against the active version
Every publish is validated against the current
active schema (JSON Schema Draft 7). A mismatch returns 400 schema_mismatch with per-field validation_errors — the event is never written.Deprecated versions still work — with a warning
If a payload only matches a
deprecated version, publish still succeeds, but the response carries an X-Webhook-Schema-Deprecated header so you know to migrate before it's sunset.Schema-change impact warnings
When you activate a new schema version, every existing Payload Transform for that Event Type is re-evaluated against the schema's example payload. Any that would now fail are returned as
transform_warnings — the schema still activates, but you're warned before subscribers see broken deliveries.
A
400 from a schema mismatch happens synchronously, inline with your publish call —
you find out immediately, not from a failed delivery attempt an hour later.