Understanding Schema Changes
How HookHound extracts webhook schemas, detects changes, and classifies breaking vs non-breaking.
How HookHound extracts webhook schemas
For each incoming event, HookHound analyzes the JSON payload and builds a normalized "shape tree" — the structure of the data without the values. Supported types: object, array, string, number, boolean, null, and unknown (for ambiguous cases).
- Objects — Properties and their types.
- Arrays — Empty arrays become items: unknown; non-empty arrays merge schema across elements.
- Canonicalization — Keys are sorted for stable comparison.
The schema is hashed (SHA-256) for fast equality checks and deduplication.
What counts as a schema change
Schema changes are tracked per integration + event type. For Stripe, the event type comes from payload.type; for other providers, the event type is inferred from the payload or defaults to unknown.
A change is recorded when the schema hash differs from the previous version for that event type. This includes:
- Added fields
- Removed fields
- Type changes (e.g. string → number)
- Kind changes (object ↔ array)
What counts as a breaking change
Breaking changes are changes that may break your integration code:
- Removed fields — Code expecting the field will fail.
- Kind changes — Object ↔ array or object ↔ primitive.
- Type changes or narrowing — e.g. string → number.
Non-breaking changes are typically safe to ignore:
- Added fields — Code that doesn't use them continues to work.
- Empty-array unknown → concrete items — Schema becomes more specific without breaking existing consumers.
What gets captured
Each event stores the JSON payload and request headers. Sensitive headers (authorization, cookie, x-api-key, etc.) and infrastructure headers (x-forwarded-*, x-vercel-*, content-length) are stripped before storage. The event detail page shows the stored payload and headers, and the "Copy as cURL" feature excludes infrastructure headers for cleaner replay commands.
How schema versions are tracked
Each unique schema (by hash) is stored as a schema version. When a new event arrives with a different schema, HookHound creates a schema change record linking the previous version to the new one. The diff is computed and stored.
How the schema timeline works
The schema timeline on the integration page shows schema versions in chronological order. Each version is labeled (e.g. Schema v1, Schema v2) with a summary of what changed from the previous version. Schema changes are deduplicated by unique transition (fromSchema → toSchema), so repeated transitions are counted once.