All Docs
FeaturesCalmony PayUpdated March 15, 2026

Spec Drift: Undocumented `whe_` ID Prefix on Webhook Endpoints

Spec Drift: Undocumented whe_ ID Prefix on Webhook Endpoints

Severity: Critical
Spec: Calmony Pay REST API Contract
Version detected: v1.0.85
Affected file: src/db/schema.ts

Background

The Calmony Pay REST API Contract is the authoritative specification for all object ID formats used across the platform. It defines a fixed, enumerated list of ID prefixes — one per object type. Every object created by the API is assigned an ID using one of these prefixes, making IDs both human-readable and programmatically distinguishable.

The Deviation

The contract specifies exactly 7 valid ID prefixes:

cus_   →  Customer
pm_    →  Payment Method
pi_    →  Payment Intent
sub_   →  Subscription
inv_   →  Invoice
cs_    →  Checkout Session
evt_   →  Event

However, the payWebhookEndpoints table in src/db/schema.ts generates IDs using the prefix whe_:

// Example of ID generated for a webhook endpoint row
// whe_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The prefix whe_ does not appear anywhere in the pinned spec. The spec makes no provision for a webhook_endpoint object type or its ID format.

Impact

  • API consumers parsing or storing webhook endpoint IDs may encounter the undocumented whe_ prefix and fail validation if they strictly enforce the spec's known prefix list.
  • Internal tooling that pattern-matches on known prefixes to determine object type will not recognise whe_ and may mis-classify or drop webhook endpoint objects.
  • The deviation creates an inconsistency between the documented contract and the live system, which could cause confusion during integrations, audits, or SDK generation.

Current Status

This deviation has been flagged as a critical spec drift item. A fix is queued in the pipeline to resolve the inconsistency — either by:

  1. Updating the pinned spec to formally enumerate whe_ as a valid prefix for webhook_endpoint objects, or
  2. Removing the whe_ prefix from the implementation and aligning with a spec-approved alternative.

No action is required from API consumers at this time, but you should not hard-code assumptions about the whe_ prefix being permanent — it may change when the fix is applied.

Recommended Caution

If your integration stores or compares webhook endpoint IDs, treat the whe_ prefix as provisional until the spec drift fix is released. Monitor the Changelog for the resolution in an upcoming version.