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

# 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](https://dashboard.stripe.com/webhooks) or via the [Stripe Webhooks API](https://docs.stripe.com/api/webhook_endpoints).

## 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.

<Info>
  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.
</Info>

### 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`](https://docs.stripe.com/api/issuing/authorizations/object#issuing_authorization_object-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](https://docs.stripe.com/issuing/purchases/authorizations) 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](/platform/additional-information/webhooks/overview) for setup instructions and the full event schema.