Webhooks

Understand how Stripe Issuing webhooks map to onchain transactions in the Bridge integration

The Bridge + Stripe Issuing integration uses Stripe Issuing webhooks for all card transaction events. Bridge webhook events are still used for customer and KYC status updates.

Webhook sources

Event type	Source	Description
Card authorizations and transactions	Stripe	issuing_authorization.* and issuing_transaction.* events
Cardholder creation	Stripe	issuing_cardholder.created
Customer and KYC updates	Bridge	customer.* events
Statement generation	Bridge API	On-demand via Bridge API

Set up your Stripe webhook endpoint in the Stripe Dashboard or via the Stripe Webhooks API.

Authorization lifecycle

When a card is used at a merchant, Bridge pulls funds onchain at the time of authorization. This triggers a sequence of Stripe and onchain events.

Authorization created

When a card is authorized, Bridge validates the linked wallet has an active onchain approval and sufficient funds, then submits an onchain transaction to pull funds just-in-time. Stripe publishes an issuing_authorization.created event.

The onchain transaction completes asynchronously—you may receive the Stripe event before the onchain transaction is confirmed.

By default, Bridge doesn’t support the real-time issuing_authorization.request webhook for approving or denying individual authorizations, due to transaction submission latency. Contact Bridge if you need real-time authorization control.

Incremental authorizations

If a merchant requests an increased authorization amount (for example, adding a tip), an additional onchain pull is submitted for the incremental amount. Each increment corresponds to an item in the request_history of the authorization and triggers an issuing_authorization.updated event.

Capture

When a merchant captures an authorization, Stripe publishes an issuing_transaction.created event. If the captured amount exceeds the originally authorized amount, Bridge submits an additional onchain pull for the difference.

Bridge may also proactively pull a small additional amount at authorization time based on the merchant category code (MCC) and the overcapture upper bound. Any difference between the proactive pull and the final captured amount is refunded once settlement is complete.

Refunds and reversals

If an authorization is partially or fully refunded, Stripe publishes an issuing_authorization.updated event with the new amount. Bridge asynchronously submits an onchain transaction to return the funds to the wallet. Multiple small refunds may be batched into a single onchain transaction.

Authorization expiry

If a merchant never captures an authorization, it eventually expires. Stripe publishes an issuing_authorization.updated event transitioning the authorization to expired. Bridge returns any remaining authorized funds to the wallet.

Key Stripe webhook events

Event	Trigger	Onchain effect
issuing_authorization.created	Card used at a merchant	Onchain pull submitted
issuing_authorization.updated	Incremental auth, refund, or expiry	Additional pull or return submitted
issuing_transaction.created	Merchant captures authorization	Additional pull if capture > auth amount
issuing_transaction.updated	Transaction state changes	None
issuing_cardholder.created	Bridge approves cards endorsement	None (managed by Bridge)

Refer to the Stripe Issuing webhooks documentation for the full event reference and payload schemas.

Bridge webhooks for customer and KYC events

Customer lifecycle events—including cards endorsement status changes—continue to be delivered via Bridge webhooks. Subscribe to the customer event category to receive updates when:

• A customer’s cards endorsement is approved (and the stripe_cardholder_id is populated)
• An endorsement is revoked (for example, after 24 hours without card creation)
• KYC requirements change

See the Bridge webhooks guide for setup instructions and the full event schema.