Spec Drift Resolved: payment_intent.failed Webhook Event Name

Release: v1.0.94

Summary

A specification deviation has been identified and resolved affecting the canonical name of the payment intent failure webhook event. If your integration listens for webhook events related to failed payment intents, you must verify your subscription uses the correct event name.

What happened

The Calmony Pay REST API Contract defines the payment intent failure webhook event as:

payment_intent.failed

The server-side implementation — both the payment intent confirmation endpoint and the subscription billing function — correctly emitted this event name. However, the test suite (webhook-events.test.ts) was documenting and asserting a different string:

payment_intent.payment_failed   ← INCORRECT (was used in tests only)

This created a silent failure scenario: any webhook endpoint registered to listen for payment_intent.payment_failed would never receive an event, because the server never emitted that string.

Correct event name

Event	Correct name
Payment intent failed	payment_intent.failed

Who is affected

You are affected if any of the following are true:

• You registered a webhook endpoint with an enabled_events list containing payment_intent.payment_failed.
• You built integration logic (e.g. retry handling, alerting, dunning workflows) that triggers on the payment_intent.payment_failed event type.
• You derived your event subscription from the test file's EXPECTED_EVENTS.paymentIntentFailed constant prior to this release.

Required action

1. Update your webhook endpoint subscription

If you registered a webhook endpoint via the API with the incorrect event name, update it to use the correct string:

PATCH /v1/webhook_endpoints/{id}
Content-Type: application/json

{
  "enabled_events": ["payment_intent.failed"]
}

2. Update any event-type comparisons in your handler

If your webhook handler checks the type field of the incoming event payload, ensure it matches the correct string:

// Before (incorrect)
if (event.type === 'payment_intent.payment_failed') { ... }

// After (correct)
if (event.type === 'payment_intent.failed') { ... }

3. Review missed events

Because the server never emitted payment_intent.payment_failed, any payment failures that occurred while your endpoint was subscribed to the wrong event name were silently undelivered. Review your payment intent records for failures you may need to handle retroactively.

No server-side changes

The server-side behaviour has not changed. The event has always been emitted as payment_intent.failed. Only the test documentation was incorrect — the fix brings tests and documentation into alignment with the spec and the existing server behaviour.