> ## Documentation Index
> Fetch the complete documentation index at: https://rain-sandbox-trial.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Event Flow

> A single swimlane showing the main card-program webhooks at the point they fire, from onboarding through spend, disputes, and reporting.

This diagram shows where the main webhooks fit across a card-issuing program, from onboarding through spend, disputes, and reporting. Most of the sequence is the same regardless of integration model, but authorization differs: Partner-Managed programs decide authorizations themselves and receive `transaction.requested`, while Rain-Managed programs skip straight to `transaction.created` because Rain decides authorizations internally. To set up your endpoint first, see [Set up webhooks](/docs/set-up-webhooks); for a flat list of every event, see the [Event catalog](/docs/event-catalog).

<div className="wf-diagram">
  <div className="legend">
    <span className="lg"><span className="swatch send" />Webhook Rain sends you</span>
    <span className="lg"><span className="swatch handle" />Your handler (ack 2xx)</span>
    <span className="lg"><span className="swatch action" />Action / API call</span>
    <span className="lg"><span className="swatch ext" />Card network</span>
    <span className="lg"><span className="swatch cond" />Conditional step</span>
    <span className="lg"><span className="swatch disp" />Exception (dispute)</span>
  </div>

  <div className="diagram-shell">
    <svg id="flow" role="img" aria-label="flow swimlane" viewBox="0 0 1080 3524" width="1080" height="3524" style={{width: "100%", height: "auto"}}><defs><marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" className="marker-fill-default" /></marker><marker id="arrowSend" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" className="marker-fill-send" /></marker><marker id="arrowDisp" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" className="marker-fill-disp" /></marker></defs><text x="20" y="380" className="phase-label" transform="rotate(-90 20 380)" text-anchor="middle">Onboarding · KYB + KYC</text><rect x="6" y="680" width="1068" height="600" className="phase-band" rx="9" /><text x="20" y="980" className="phase-label" transform="rotate(-90 20 980)" text-anchor="middle">Collateral</text><text x="20" y="1780" className="phase-label" transform="rotate(-90 20 1780)" text-anchor="middle">Card issuance & wallet</text><rect x="6" y="2280" width="1068" height="700" className="phase-band" rx="9" /><text x="20" y="2630" className="phase-label" transform="rotate(-90 20 2630)" text-anchor="middle">Purchase & settlement</text><text x="20" y="3080" className="phase-label" transform="rotate(-90 20 3080)" text-anchor="middle">Dispute</text><rect x="6" y="3180" width="1068" height="334" className="phase-band" rx="9" /><text x="20" y="3347" className="phase-label" transform="rotate(-90 20 3347)" text-anchor="middle">Reporting</text><line x1="138" y1="70" x2="138" y2="3512" className="lane-line" stroke-width="1.5" stroke-dasharray="2 6" /><line x1="347" y1="70" x2="347" y2="3512" className="lane-line" stroke-width="1.5" stroke-dasharray="2 6" /><line x1="556" y1="70" x2="556" y2="3512" className="lane-line" stroke-width="1.5" stroke-dasharray="2 6" /><line x1="765" y1="70" x2="765" y2="3512" className="lane-line" stroke-width="1.5" stroke-dasharray="2 6" /><line x1="974" y1="70" x2="974" y2="3512" className="lane-line" stroke-width="1.5" stroke-dasharray="2 6" /><path d="M 974 168 C 974 184, 138 184, 138 200" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 268 C 138 284, 974 284, 974 300" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 368 C 974 384, 556 384, 556 400" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 556 468 C 556 484, 138 484, 138 500" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 568 C 138 584, 974 584, 974 600" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 668 C 974 684, 138 684, 138 700" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 768 L 138 800" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 868 C 138 884, 974 884, 974 900" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 968 C 974 984, 556 984, 556 1000" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 556 1068 C 556 1084, 138 1084, 138 1100" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 1168 C 138 1184, 974 1184, 974 1200" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 1268 L 974 1300" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 974 1368 C 974 1384, 138 1384, 138 1400" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 1468 L 138 1500" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 1568 C 138 1584, 974 1584, 974 1600" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 1668 C 974 1684, 556 1684, 556 1700" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 556 1768 C 556 1784, 138 1784, 138 1800" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 1868 C 138 1884, 974 1884, 974 1900" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 1968 C 974 1984, 556 1984, 556 2000" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 556 2068 C 556 2084, 138 2084, 138 2100" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 2168 C 138 2184, 974 2184, 974 2200" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 2268 C 974 2284, 556 2284, 556 2300" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 556 2368 C 556 2384, 347 2384, 347 2400" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 347 2468 C 347 2484, 138 2484, 138 2500" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 2568 L 138 2600" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 138 2668 C 138 2684, 974 2684, 974 2700" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 2768 C 974 2784, 138 2784, 138 2800" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 2868 C 138 2884, 974 2884, 974 2900" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><path d="M 974 2968 C 974 2984, 138 2984, 138 3000" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 3068 C 138 3084, 974 3084, 974 3100" fill="none" className="conn-disp" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowDisp)" opacity="0.92" /><path d="M 974 3168 C 974 3184, 138 3184, 138 3200" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 3268 L 138 3300" fill="none" className="conn-default" stroke-width="1.7" marker-end="url(#arrow)" opacity="0.92" /><path d="M 138 3368 C 138 3384, 974 3384, 974 3400" fill="none" className="conn-send" stroke-width="1.7" stroke-dasharray="5 4" marker-end="url(#arrowSend)" opacity="0.92" /><foreignObject x="44" y="16" width="188" height="54"><div className="lane-head rain"><span className="ico">🌧️</span><span className="nm">Rain (issuer · processor)</span></div></foreignObject><foreignObject x="253" y="16" width="188" height="54"><div className="lane-head"><span className="ico">🌐</span><span className="nm">Card network</span></div></foreignObject><foreignObject x="462" y="16" width="188" height="54"><div className="lane-head"><span className="ico">👤</span><span className="nm">Cardholder</span></div></foreignObject><foreignObject x="671" y="16" width="188" height="54"><div className="lane-head"><span className="ico">📱</span><span className="nm">Partner app (UI)</span></div></foreignObject><foreignObject x="880" y="16" width="188" height="54"><div className="lane-head"><span className="ico">🖥️</span><span className="nm">Partner backend (you)</span></div></foreignObject><foreignObject x="880" y="100" width="188" height="68"><div className="card api cond"><span className="bn">1</span><span className="ct"><span className="tag">Corporate only</span><span className="lab">Submit company for KYB</span></span></div></foreignObject><foreignObject x="44" y="200" width="188" height="68"><div className="card send cond"><span className="bn">2</span><span className="ct"><span className="tag">Webhook · KYB</span><span className="lab mono">company.updated</span></span></div></foreignObject><foreignObject x="880" y="300" width="188" height="68"><div className="card handle cond"><span className="bn">3</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="462" y="400" width="188" height="68"><div className="card action"><span className="bn">4</span><span className="ct"><span className="tag">Cardholder</span><span className="lab">Sign up & submit KYC</span></span></div></foreignObject><foreignObject x="44" y="500" width="188" height="68"><div className="card send"><span className="bn">5</span><span className="ct"><span className="tag">Webhook · KYC</span><span className="lab mono">user.updated</span></span></div></foreignObject><foreignObject x="880" y="600" width="188" height="68"><div className="card handle"><span className="bn">6</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="44" y="700" width="188" height="68"><div className="card action"><span className="bn">7</span><span className="ct"><span className="tag">Rain · on-chain</span><span className="lab">Deploy collateral contract</span></span></div></foreignObject><foreignObject x="44" y="800" width="188" height="68"><div className="card send"><span className="bn">8</span><span className="ct"><span className="tag">Webhook · per-user</span><span className="lab mono">contract.created</span></span></div></foreignObject><foreignObject x="880" y="900" width="188" height="68"><div className="card handle"><span className="bn">9</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="462" y="1000" width="188" height="68"><div className="card action"><span className="bn">10</span><span className="ct"><span className="tag">Cardholder · on-chain</span><span className="lab">Deposit collateral</span></span></div></foreignObject><foreignObject x="44" y="1100" width="188" height="68"><div className="card send"><span className="bn">11</span><span className="ct"><span className="tag">Webhook · collateral</span><span className="lab mono">transaction.created</span></span></div></foreignObject><foreignObject x="880" y="1200" width="188" height="68"><div className="card handle"><span className="bn">12</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="880" y="1300" width="188" height="68"><div className="card api"><span className="bn">13</span><span className="ct"><span className="tag">POST</span><span className="lab">Create card</span></span></div></foreignObject><foreignObject x="44" y="1400" width="188" height="68"><div className="card action"><span className="bn">14</span><span className="ct"><span className="tag">Rain</span><span className="lab">Issue card</span></span></div></foreignObject><foreignObject x="44" y="1500" width="188" height="68"><div className="card send"><span className="bn">15</span><span className="ct"><span className="tag">Webhook</span><span className="lab mono">card.created</span></span></div></foreignObject><foreignObject x="880" y="1600" width="188" height="68"><div className="card handle"><span className="bn">16</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="462" y="1700" width="188" height="68"><div className="card action"><span className="bn">17</span><span className="ct"><span className="tag">Cardholder</span><span className="lab">Activate card</span></span></div></foreignObject><foreignObject x="44" y="1800" width="188" height="68"><div className="card send"><span className="bn">18</span><span className="ct"><span className="tag">Webhook · active</span><span className="lab mono">card.updated</span></span></div></foreignObject><foreignObject x="880" y="1900" width="188" height="68"><div className="card handle"><span className="bn">19</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="462" y="2000" width="188" height="68"><div className="card action"><span className="bn">20</span><span className="ct"><span className="tag">Cardholder</span><span className="lab">Add card to Apple / Google Pay</span></span></div></foreignObject><foreignObject x="44" y="2100" width="188" height="68"><div className="card send cond"><span className="bn">21</span><span className="ct"><span className="tag">Webhook · if declined</span><span className="lab mono">card.notification</span></span></div></foreignObject><foreignObject x="880" y="2200" width="188" height="68"><div className="card handle cond"><span className="bn">22</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="462" y="2300" width="188" height="68"><div className="card action"><span className="bn">23</span><span className="ct"><span className="tag">Cardholder</span><span className="lab">Make a purchase</span></span></div></foreignObject><foreignObject x="253" y="2400" width="188" height="68"><div className="card ext"><span className="bn">24</span><span className="ct"><span className="tag">Network</span><span className="lab">Authorization request</span></span></div></foreignObject><foreignObject x="44" y="2500" width="188" height="68"><div className="card send cond"><span className="bn">25</span><span className="ct"><span className="tag">Webhook · Partner-Managed only</span><span className="lab mono">transaction.requested</span></span></div></foreignObject><foreignObject x="44" y="2600" width="188" height="68"><div className="card send"><span className="bn">26</span><span className="ct"><span className="tag">Webhook · spend</span><span className="lab mono">transaction.created</span></span></div></foreignObject><foreignObject x="880" y="2700" width="188" height="68"><div className="card handle"><span className="bn">27</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="44" y="2800" width="188" height="68"><div className="card send"><span className="bn">28</span><span className="ct"><span className="tag">Webhook</span><span className="lab mono">transaction.completed</span></span></div></foreignObject><foreignObject x="880" y="2900" width="188" height="68"><div className="card handle"><span className="bn">29</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="44" y="3000" width="188" height="68"><div className="card dispute"><span className="bn">30</span><span className="ct"><span className="tag">Webhook · if disputed</span><span className="lab mono">dispute.created</span></span></div></foreignObject><foreignObject x="880" y="3100" width="188" height="68"><div className="card handle"><span className="bn">31</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="44" y="3200" width="188" height="68"><div className="card action"><span className="bn">32</span><span className="ct"><span className="tag">Rain · periodic</span><span className="lab">Generate statement / report</span></span></div></foreignObject><foreignObject x="44" y="3300" width="188" height="68"><div className="card send"><span className="bn">33</span><span className="ct"><span className="tag">Webhook · periodic</span><span className="lab mono">report.created</span></span></div></foreignObject><foreignObject x="880" y="3400" width="188" height="68"><div className="card handle"><span className="bn">34</span><span className="ct"><span className="tag">Handle</span><span className="lab">ack 2xx</span></span></div></foreignObject><foreignObject x="300" y="204" width="472" height="60"><div className="callout"><span className="co-t">⚑ Company KYB: corporate programs only</span><span className="co-s">Consumer programs skip KYB and start at cardholder KYC ↓</span></div></foreignObject></svg>
  </div>
</div>

## Situational and program-specific steps

Some steps in the diagram do not happen for every program, or fire only in specific situations:

| Step                                                                                                                                                     | When it fires                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization ([`transaction.requested`](/docs/transaction#transaction-requested))                                                                       | Partner-Managed programs only. Rain-Managed programs skip `transaction.requested` and go straight to [`transaction.created`](/docs/transaction#transaction-created), because Rain decides authorizations internally. |
| Company KYB ([`company.updated`](/docs/identity-and-compliance#company-updated))                                                                         | Corporate programs only. Consumer programs skip it and start at cardholder KYC.                                                                                                                                      |
| Collateral ([`contract.created`](/docs/account-and-reports#contract-created), collateral [`transaction.created`](/docs/transaction#transaction-created)) | Only when each user posts their own collateral. Pooled-collateral programs deploy one contract at setup instead, not one per cardholder.                                                                             |
| Card activation ([`card.updated`](/docs/card#card-updated))                                                                                              | For every card. Physical cards activate after they arrive; virtual cards activate immediately.                                                                                                                       |
| Wallet provisioning ([`card.notification`](/docs/card#card-notification))                                                                                | Only when adding a card to a digital wallet is declined. A successful add sends [`card.updated`](/docs/card#card-updated) with `statusChangeReason: wallet_provisioned` instead.                                     |
| Reporting ([`report.created`](/docs/account-and-reports#report-created))                                                                                 | On a schedule, at the program level (statements and reports), not per cardholder.                                                                                                                                    |

## What's next

<Columns cols={2}>
  <Card title="Set up webhooks" icon="gear" href="/docs/set-up-webhooks">
    Register your endpoint, choose a signing key, and verify signatures.
  </Card>

  <Card title="Event catalog" icon="table-list" href="/docs/event-catalog">
    Look up any event by category, delivery model, and trigger.
  </Card>
</Columns>
