PayoutModuleEvents from @mercurjs/types. payout.webhook_received carries provider webhooks to the shipped subscriber; the others come from the payout workflows. Medusa also emits a created, updated, or deleted event whenever a payout record changes. Subscribe to these for side effects such as seller notifications or operator alerts.
PayoutModuleEvents
Like Medusa’s payment events, the payloads carry only the row’s id; retrieve the account, payout or reversal in the subscriber for anything else.
payout.failed and payout.reversal_failed are emitted once per row that the provider refused in that run. A row the provider refused for good is aborted and emits nothing.
Webhook event
ThePOST /hooks/payout route emits payout.webhook_received with a 5000 ms delay and 3 attempts. data is the parsed body, rawData is the raw body, and headers are the request headers.
The payout-webhook subscriber, with subscriber id payout-webhook-handler, parses it through the provider and runs processPayoutForWebhookWorkflow. The event bus serializes rawData as a buffer object, and the subscriber turns it back into a Buffer before signature checks. Other subscribers can listen to the same event; the Stripe connector plugin uses it to record bank payout events on its settlements.
Data-model events
PayoutModuleService extends MedusaService, so Medusa emits an event for each row it creates, updates, or deletes. The name is the module name, the kebab-case model name, and the action. The payload is { id }.
An
updated event fires for every write. Subscribe to payout_account.updated instead when you only care about provider syncs, and read the account’s new status in the subscriber:
src/subscribers/payout-account-updated.ts
restricted, which is where you’d send the seller a reminder to finish onboarding.
Workflow hook
createOrderPayoutsWorkflow exposes a payoutsCreated hook with { order_ids, payouts }, where payouts are the payouts sent to the provider in that run. Use it when you need the order ids with the result.