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 different cases such as when a payment is being processed asynchronously or when a request is interrupted.

---

processEvent Method

The Payment Module’s main service (IPaymentModuleService) provides a processEvent method used to handle incoming webhook events from third-party providers. The method delegates the handling to the associated payment provider, which returns the event's details.

If the event's details indicate that the payment should be authorized, then the authorizePaymentSession 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 of the main service is executed on the payment of the specified payment session.

You can use this method in your webhook listener API routes or endpoints.

Note

Medusa V2 implements a webhook listener at the /hooks/payment/[provider] API route, where [provider] is the ID of the provider (for example, stripe). You can use that webhook listener in your third-party payment provider's configurations.

For example:

await paymentModuleService.processEvent({
  provider: "stripe",
  payload: {
    // webhook event data
  },
})

Learn more about the method’s parameters and return types in this reference.