> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Process payout provider webhooks

> Route provider webhooks to Mercur so payout accounts and payouts pick up the provider's status changes.

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](https://docs.stripe.com/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.

**1. 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](https://docs.mercurjs.com/resources/integrations/stripe-connect/configuration.md#webhooks). Locally, forward Connect events with the Stripe CLI:

```bash theme={null}
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`.

**2. 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:

```ts title="src/subscribers/payout-webhook.ts (in @mercurjs/core)" theme={null}
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.

**3. Check the account status**

Read the account to confirm the update landed:

```ts theme={null}
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:

```ts theme={null}
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:

```ts title="src/providers/acme-payouts/service.ts" theme={null}
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:

```ts theme={null}
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](https://docs.mercurjs.com/platform/payout/concepts/account-lifecycle.md) for every action and the status it sets
* [Events reference](https://docs.mercurjs.com/platform/payout/reference/events.md) for the `payout.webhook_received` payload


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.