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

# Webhooks overview

> Configure HTTPS endpoints, understand delivery retries, and receive RaaS Widgets Partner events in real time

## What are webhooks?

Webhooks are HTTP POST callbacks RaaS Widgets sends to your server when Partner events occur. Instead of polling, you get notified when:

* A magic link is created or opened
* An end user is created or gains a participation role (`sender` / `receiver`)
* The platform needs additional user data for CIP, or CIP completes
* An operation is created, completed, failed, or cancelled
* A legacy Request Money or deferred payout API call succeeds or fails

```mermaid theme={null}
sequenceDiagram
    participant Partner
    participant RaaS as RaaS Widgets
    participant Server as Partner server
    participant User

    Partner->>RaaS: POST /partner/links
    RaaS->>Server: link.created
    Server-->>RaaS: 200 OK

    User->>RaaS: Opens magic link
    RaaS->>Server: link.opened
    Server-->>RaaS: 200 OK

    opt CIP data incomplete
      RaaS->>Server: user.data_request
      Server->>RaaS: PUT /partner/data-requests/:id
    end

    User->>RaaS: Creates operation
    RaaS->>Server: operation.created
    RaaS->>Server: operation.completed<br/>or failed / cancelled
```

## Configuration

Configure your webhook URL in the [Partner Portal](https://raas-widgets-partner-portal-sandbox.up.railway.app/):

1. Open **Settings → Webhooks**
2. Enter an HTTPS endpoint URL
3. Save and copy the webhook secret for signature verification

<Warning>
  Your endpoint must use HTTPS. HTTP endpoints are not supported.
</Warning>

### Per-link override

Pass `callbackUrl` on create to override the partner default for that link:

```json theme={null}
{
  "referenceId": "user_123",
  "flow": "smart",
  "callbackUrl": "https://api.yourcompany.com/webhooks/raas-widgets/special"
}
```

## Request format

```json theme={null}
{
  "event": "link.opened",
  "timestamp": "2026-07-23T14:30:00.000Z",
  "data": {}
}
```

### Headers

| Header             | Description                     |
| ------------------ | ------------------------------- |
| `Content-Type`     | `application/json`              |
| `X-RAAS-Event`     | Event type (e.g. `link.opened`) |
| `X-RAAS-Timestamp` | Unix timestamp (seconds)        |
| `X-RAAS-Signature` | HMAC-SHA256 signature           |

See [Webhook security](/raas-widgets/webhooks/security) for verification.

## Events

| Event                     | Description                                   |
| ------------------------- | --------------------------------------------- |
| `link.created`            | Magic link minted                             |
| `link.opened`             | User opened the link                          |
| `user.created`            | End-user first created for a `referenceId`    |
| `user.role_added`         | First participation as `sender` or `receiver` |
| `user.data_request`       | Missing CIP fields — reply via PUT            |
| `user.cip_verified`       | CIP approved                                  |
| `user.cip_failed`         | CIP rejected                                  |
| `user.cip_manual_review`  | CIP needs manual review                       |
| `operation.created`       | Transfer operation created                    |
| `operation.completed`     | Transfer settled                              |
| `operation.failed`        | Transfer failed                               |
| `operation.cancelled`     | Operation cancelled                           |
| `request_money.created`   | Request API created ask + fund-request link   |
| `request_money.failed`    | Request API error                             |
| `deferred_payout.created` | Deferred payout origination created           |
| `deferred_payout.updated` | Deferred payout binding changed               |
| `deferred_payout.failed`  | Deferred payout API error                     |

Full payloads: [Webhook events](/raas-widgets/webhooks/events). Status meanings: [Operation lifecycle](/raas-widgets/ops/operation-lifecycle).

## Delivery and retries

If your endpoint returns a non-2xx status or times out, RaaS Widgets retries with backoff (up to 5 attempts), for example:

| Attempt | Delay after failure |
| ------- | ------------------- |
| 1       | Immediate           |
| 2       | \~1 minute          |
| 3       | \~5 minutes         |
| 4       | \~30 minutes        |
| 5       | \~2 hours           |

* **Timeout:** respond within **30 seconds**
* **Success:** HTTP `2xx`
* After the last failure, delivery is marked failed (replay from Partner Portal / support tools when available)

<Tip>
  Return `200` immediately, then process asynchronously. Keep handlers idempotent — deliveries can repeat.
</Tip>

## Best practices

<AccordionGroup>
  <Accordion title="Verify every request">
    Reject unsigned or invalid signatures before parsing business logic.
  </Accordion>

  <Accordion title="Handle unknown events">
    New event types may appear. Acknowledge with `200` and log unknowns.
  </Accordion>

  <Accordion title="Log payloads">
    Retain event bodies for audit and support — redact PII as required by your policy.
  </Accordion>
</AccordionGroup>

## Sandbox testing

1. Point the Partner Portal webhook URL at an HTTPS tunnel (e.g. ngrok)
2. Create a sandbox link with `raas_sandbox_*`
3. Confirm `link.created`, open the URL, then exercise data-request / operation flows as needed

## Next steps

<CardGroup cols={2}>
  <Card title="Events" icon="list" href="/raas-widgets/webhooks/events">
    Payload reference for each event.
  </Card>

  <Card title="Security" icon="shield" href="/raas-widgets/webhooks/security">
    HMAC verification examples.
  </Card>
</CardGroup>