Fix: payment_method.attached Webhook Now Fires on Hosted Checkout

Release: v1.0.113

Overview

A conformance issue with the Calmony Pay REST API Contract has been resolved. Going forward, the payment_method.attached webhook event is correctly emitted whenever a payment method is attached to a customer — including through the hosted checkout flow.

What Was the Problem?

The hosted checkout session callback (POST /api/v1/checkout/sessions/callback) handles the end of a checkout flow by:

1. Tokenising the customer's card with Cardstream.
2. Creating a PaymentMethod record in the database.
3. Associating that payment method with the customer by setting customerId.

While steps 1–3 completed successfully, the route never emitted a payment_method.attached webhook event after attaching the method. This was a deviation from the API contract, which mandates that a payment_method.attached event is fired any time a payment method is attached to a customer, regardless of the attachment path.

What Changed?

The checkout session callback route (src/app/api/v1/checkout/sessions/callback/route.ts) now calls emitPayEvent with event type "payment_method.attached" immediately after the payment method is attached to the customer.

No changes to the webhook payload shape, delivery mechanism, or subscription model were made — only the missing emission was added.

Who Is Affected?

This fix affects merchants who subscribe to the payment_method.attached webhook event. Previously, subscriptions to this event would only fire when a payment method was attached via the direct API (POST /api/v1/payment-methods). After this fix, the event fires consistently across all attachment paths, including:

• Direct API calls to attach a payment method to a customer.
• Cards tokenised and attached automatically at the end of a hosted checkout session.

Subscribing to payment_method.attached

If you are not yet subscribed to this event and want to be notified whenever a customer's card is saved, register a webhook endpoint for the payment_method.attached event type:

POST /api/v1/webhooks

{
  "url": "https://your-app.example.com/webhooks/calmony",
  "events": ["payment_method.attached"]
}

Example Event Payload

{
  "type": "payment_method.attached",
  "data": {
    "object": {
      "id": "pm_xxxxxxxxxxxxxxxx",
      "customerId": "cus_xxxxxxxxxxxxxxxx",
      "card": {
        "brand": "visa",
        "last4": "4242",
        "expMonth": 12,
        "expYear": 2027
      }
    }
  }
}

Note: The exact fields in the data.object payload match the PaymentMethod schema documented in the API Reference.

Upgrade Notes

No action is required to receive this fix — it is applied automatically. If your integration relies on payment_method.attached webhooks to trigger downstream logic (e.g. updating a CRM, sending a confirmation email, or enabling a saved-card payment UI), verify that your webhook handler is idempotent, as events that were previously silently dropped will now be delivered for any checkout sessions completed after upgrading to v1.0.113.