Event conventions
Naming, deduplication, and versioning for Stripe events.
reference • updated 2026-03-15
Naming convention
- Use
<domain>.<resource>.<action>for public event names. - Avoid ambiguous verbs (
updated) without business context. - Keep event names stable to reduce consumer breakage.
Keys and deduplication
| Type | Recommended field | Purpose |
|---|---|---|
| Technical event | event.id | dedupe provider re-deliveries |
| Business operation | checkout.session.id (or equivalent functional id) | enforce logical uniqueness |
| Mutable request | Idempotency-Key | prevent double execution on retries |
Versioning rules
- Breaking changes require a new schema/event version.
- New fields should be optional by default.
- Deprecations should include an explicit communication window in changelog.
Recommended minimum envelope
{
"event_id": "evt_123",
"event_type": "billing.checkout.completed",
"occurred_at": "2026-03-15T12:00:00Z",
"organization_id": "org_123",
"payload": {}
}