Webhook Events

In this document, you’ll learn how the Payment Module supports listening to webhook events.

What's a Webhook Event?#

A webhook event is sent from a third-party payment provider to your application. It indicates a change in a payment’s status.

This is useful in many cases such as when a payment is being processed asynchronously or when a request is interrupted and the payment provider is sending details on the process later.

---

getWebhookActionAndData Method#

The Payment Module’s main service has a getWebhookActionAndData method used to handle incoming webhook events from third-party payment services. The method delegates the handling to the associated payment provider, which returns the event's details.

Medusa implements a webhook listener route at the /hooks/payment/[identifier]_[provider] API route, where:

• [identifier] is the identifier static property defined in the payment provider. For example, stripe.
• [provider] is the ID of the provider. For example, stripe.

For example, when integrating basic Stripe payments with the Stripe Module Provider, the webhook listener route is /hooks/payment/stripe_stripe. If you're integrating Stripe's Bancontact payments, the webhook listener route is /hooks/payment/stripe-bancontact_stripe.

Use that webhook listener in your third-party payment provider's configurations.

If the event's details indicate that the payment should be authorized, then the authorizePaymentSession method of the main service is executed on the specified payment session.

If the event's details indicate that the payment should be captured, then the capturePayment method of the main service is executed on the payment of the specified payment session.

Actions After Webhook Payment Processing#

After the payment webhook actions are processed and the payment is authorized or captured, the Medusa application completes the cart associated with the payment's collection if it's not completed yet.

Edit this page