Developer portal

billing.subscription.updated.v1

The tenant plan, seat count, or trial state changed.

Event typesbilling.subscription.updated.v1

billing.subscription.updated.v1v1at-least-once delivery

Fires when

On plan upgrade/downgrade, seat count change, trial activation, or trial expiry. Scoped to tenant-owner role. Not fired for per-feature-flag toggles.

Payload fields

Envelope fields are shared across all event types. Event-specific data is nested under data.

Field	Type	Required	Description
`eventId`	string (uuid)	required	Unique per delivery attempt. Use for deduplication.
`event`	string	required	Fully-qualified event name, e.g. record.created.v1.
`tenantId`	string (uuid)	required	Tenant that owns the affected resource.
`firedAt`	string (date-time)	required	ISO-8601 UTC timestamp when the event was emitted.
`data.tenantId`	string (uuid)	required	Affected tenant (same as envelope tenantId — repeated for convenience).
`data.plan`	string	required	New plan key, e.g. business or enterprise.
`data.seats`	integer	required	New seat count after the change.
`data.status`	"trialing" \| "active" \| "past_due" \| "cancelled"	required	New subscription status.
`data.effectiveAt`	string (date-time)	required	When the new plan/status takes effect.

Sample payload

{
  "eventId": "11111111-aaaa-bbbb-cccc-dddddddddddd",
  "event": "billing.subscription.updated.v1",
  "tenantId": "00000000-1111-2222-3333-444444444444",
  "firedAt": "2026-04-18T13:25:00.000Z",
  "data": {
    "tenantId": "00000000-1111-2222-3333-444444444444",
    "plan": "enterprise",
    "seats": 250,
    "status": "active",
    "effectiveAt": "2026-05-01T00:00:00.000Z"
  }
}

Verify the signature

Every delivery includes X-QEHS-Signature: sha256=<hex> and X-Job-ID headers. Verify before trusting the body. See the webhooks signature docs for a full verification example.

← All event types