Register a webhook endpoint subscribed to payout.created, payout.paid, and payout.failed events in your Stripe dashboard or via the API.
Verify each incoming webhook signature using Stripe's library (stripe.webhooks.constructEvent) with your endpoint's signing secret to reject forged requests.
On payout.paid, mark the corresponding payout record in your internal ledger as settled and trigger downstream accounting entries.
On payout.failed, extract the failure_code and failure_message from the payout object; common codes include account_closed, no_account, and insufficient_funds.
For failed payouts, update the connected account's external bank account if the failure indicates stale banking details, then re-trigger a payout.
Implement idempotency in your webhook handler using the event ID to avoid processing the same event twice on retries.
Known gotchas
Stripe retries webhook delivery on failures; your handler must be idempotent — use the event.id as a deduplication key in your database.
payout.failed does not automatically retry the payout — you must explicitly create a new Payout object after resolving the underlying issue.
For connected accounts, webhook events for payouts appear on the connected account, not the platform account — subscribe at the connected account level or use Connect webhook event filtering.
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?