Process payout provider webhooks

Connect your payout provider’s webhooks to Mercur so account and payout statuses follow the provider. You need this before any Stripe Connect account can become active.

Before you begin

You need:

A payout provider registered on the payout module, such as Stripe Connect
For Stripe Connect, a webhook signing secret set as the provider’s webhookSecret option
The Stripe CLI for local testing

Receive webhooks

Mercur ships the route, the subscriber, and the workflow. You point the provider at the route and check the result.

Point the provider at /hooks/payout

In production, add a Stripe webhook endpoint for events on connected accounts, with the URL https://your_backend_url/hooks/payout and the account.updated event. The Stripe connector plugin also needs the bank payout.* events, see its webhooks. Locally, forward Connect events with the Stripe CLI:

stripe listen --events account.updated,payout.paid,payout.failed,payout.canceled,payout.updated \
  --forward-connect-to localhost:9000/hooks/payout

The CLI prints a signing secret. Use it as the provider’s webhookSecret.

Let the subscriber run the workflow

The route emits payout.webhook_received with the body, raw body, and headers. It delays the event by 5000 ms and retries up to 3 times. The shipped payout-webhook subscriber then parses it and runs the workflow:

src/subscribers/payout-webhook.ts (in @mercurjs/core)

const processedEvent = await payoutService.getWebhookActionAndData({
  data: input.data as Record<string, unknown>,
  rawData: input.rawData,
  headers: input.headers as Record<string, unknown>,
})

if (!processedEvent.data || processedEvent.action === "not_supported") {
  return
}

const wfEngine = container.resolve(Modules.WORKFLOW_ENGINE)
await wfEngine.run(processPayoutForWebhookWorkflowId, {
  input: processedEvent,
})

Stripe Connect verifies the stripe-signature header against webhookSecret. A bad signature throws, and the event bus retries.

Check the account status

Read the account to confirm the update landed:

const payoutService = container.resolve(MercurModules.PAYOUT)

const account = await payoutService.retrievePayoutAccount(
  "pacc_01JD8Q1234567"
)

The workflow re-read the account from Stripe, so status, payouts_enabled, kyc_status, and last_synced_at match Stripe’s current view.

Run the workflow directly

processPayoutForWebhookWorkflow takes a PayoutWebhookResult, so you can apply a provider event without a webhook, for example in a test or a backfill script:

import { processPayoutForWebhookWorkflow } from "@mercurjs/core/workflows"

await processPayoutForWebhookWorkflow(container).run({
  input: {
    action: "payout.paid",
    data: { id: "tr_1QxYz" },
  },
})

data.id is the provider’s id. An account.* action looks the account up by external_id and re-syncs it from the provider. payout.paid and payout.failed carry Mercur’s payout id in data.payout_id, which providers echo from the payout_id metadata sent with the payout, and set that payout’s status. payout.paid also stores data.id as the payout’s data.provider.id, which a later reversal is sent against; payout.failed stores status_reason: "provider_error" with the webhook’s data.status_reason in data.status_detail. Any other action, an unknown id, or a missing data.id changes nothing.

Map webhooks in your own provider

When you write a provider, getWebhookActionAndData decides what each webhook means. Return the action and the provider’s own id for the account or payout:

src/providers/acme-payouts/service.ts

async getWebhookActionAndData(
  payload: PayoutWebhookActionInput
): Promise<PayoutWebhookResult> {
  const body = payload.data as { type: string; transfer_id: string }

  if (body.type === "transfer.settled") {
    return { action: "payout.paid", data: { id: body.transfer_id } }
  }

  return { action: "not_supported" }
}

Verify the provider’s signature here with payload.rawData and payload.headers before you trust the body. The route keeps the raw body for this purpose.

Emit the event from another route

If your provider must post to a different URL, emit payout.webhook_received yourself with the same shape. The shipped subscriber picks it up, and so does any other subscriber on that event, such as the Stripe connector plugin’s handler for bank payout events:

const eventBus = container.resolve(Modules.EVENT_BUS)

await eventBus.emit({
  name: "payout.webhook_received",
  data: { data: req.body, rawData: req.rawBody, headers: req.headers },
})

Enable preserveRawBody on that route’s body parser, or signature checks will fail.

Next steps

Account lifecycle for every action and the status it sets
Events reference for the payout.webhook_received payload

Store

Catalog

Offer

Attribute

Product Edit

Order Group

Commission

Payout

Review

Before you begin

Receive webhooks

Run the workflow directly

Map webhooks in your own provider

Emit the event from another route

Next steps

​Before you begin

​Receive webhooks

​Run the workflow directly

​Map webhooks in your own provider

​Emit the event from another route

​Next steps

Before you begin

Receive webhooks

Run the workflow directly

Map webhooks in your own provider

Emit the event from another route

Next steps