Webhooks overview

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

Configuration

Configure your webhook URL in the Partner Portal:

Open Settings → Webhooks
Enter an HTTPS endpoint URL
Save and copy the webhook secret for signature verification

Your endpoint must use HTTPS. HTTP endpoints are not supported.

Per-link override

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

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

Request format

{
  "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 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. Status meanings: 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)

Return 200 immediately, then process asynchronously. Keep handlers idempotent — deliveries can repeat.

Best practices

Verify every request

Reject unsigned or invalid signatures before parsing business logic.

Handle unknown events

New event types may appear. Acknowledge with 200 and log unknowns.

Log payloads

Retain event bodies for audit and support — redact PII as required by your policy.

Sandbox testing

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

Getting Started

Request API

Concepts

Integration

Flows

Webhooks

Operations

What are webhooks?

Configuration

Per-link override

Request format

Headers

Events

Delivery and retries

Best practices

Sandbox testing

Next steps

Events

Security

​What are webhooks?

​Configuration

​Per-link override

​Request format

​Headers

​Events

​Delivery and retries

​Best practices

​Sandbox testing

​Next steps

Events

Security

What are webhooks?

Configuration

Per-link override

Request format

Headers

Events

Delivery and retries

Best practices

Sandbox testing

Next steps