Webhook events

Event types

Event	Description
`link.created`	A magic link was created
`link.opened`	User opened a magic link
`user.created`	End-user record first created for a `referenceId`
`user.role_added`	First time the user participated as `sender` or `receiver`
`user.data_request`	Platform needs additional user data for CIP
`user.cip_verified`	CIP identity check approved
`user.cip_failed`	CIP identity check rejected
`user.cip_manual_review`	CIP identity check needs manual review
`operation.created`	A money transfer operation was created
`operation.completed`	An operation settled successfully
`operation.failed`	An operation failed permanently
`operation.cancelled`	An operation was cancelled
`request_money.created`	Request API created a money request + fund-request link
`request_money.failed`	Request API call failed
`deferred_payout.created`	Deferred payout origination created / first binding
`deferred_payout.updated`	Deferred payout binding or operation linkage changed
`deferred_payout.failed`	Deferred payout API call failed

Delivery headers: X-RAAS-Event, X-RAAS-Timestamp, and X-RAAS-Signature. See Webhook security.

New event types may appear. Always acknowledge with HTTP 2xx and ignore unknowns safely. For operation status meanings, see Operation lifecycle.

Sandbox API base: https://raas-widgets-backend-sandbox.up.railway.app

link.created

{
  "event": "link.created",
  "timestamp": "2026-07-23T14:30:00.000Z",
  "data": {
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "url": "https://<flow-host>/link_acme_a1b2c3d4e5f6",
    "status": "created",
    "expiresAt": "2026-07-24T14:30:00.000Z",
    "createdAt": "2026-07-23T14:30:00.000Z"
  }
}

Use this to persist the link and deliver url to your user asynchronously.

link.opened

{
  "event": "link.opened",
  "timestamp": "2026-07-23T14:30:00.000Z",
  "data": {
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "openedAt": "2026-07-23T14:30:00.000Z",
    "deviceInfo": {
      "userAgent": "Mozilla/5.0 …",
      "platform": "iOS",
      "language": "en-US"
    }
  }
}

user.created

{
  "event": "user.created",
  "timestamp": "2026-07-30T14:30:00.000Z",
  "data": {
    "userId": "usr_a1b2c3d4e5f6g7h8",
    "referenceId": "user_12345",
    "cipStatus": "pending",
    "rolesParticipated": [],
    "source": "claim",
    "createdAt": "2026-07-30T14:30:00.000Z"
  }
}

Fired the first time RaaS Widgets creates a User for your referenceId (typically on magic-link claim). source is one of claim, request_money, deferred_payout_bind, terms_accept, debug, or system. Correlate later events with userId / referenceId. Money movement still uses operation.*.

user.role_added

{
  "event": "user.role_added",
  "timestamp": "2026-07-30T14:35:00.000Z",
  "data": {
    "userId": "usr_a1b2c3d4e5f6g7h8",
    "referenceId": "user_12345",
    "role": "sender",
    "rolesParticipated": ["sender"],
    "rolesParticipatedAt": {
      "sender": "2026-07-30T14:35:00.000Z"
    },
    "operationId": "op_acme_x1y2z3",
    "linkId": "link_acme_a1b2c3d4e5f6"
  }
}

Emitted once per role the first time the user participates as sender (funded / created an operation or deferred origination) or receiver (minted a money request or claimed a deferred payout). Optional correlation fields: operationId, requestId, originationId, linkId. Roles are additive history, not entitlements — they do not skip CIP.

user.data_request

{
  "event": "user.data_request",
  "timestamp": "2026-07-23T14:30:00.000Z",
  "data": {
    "dataRequestId": "dr_acme_x9y8z7w6v5u4",
    "referenceId": "user_12345",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "requiredFields": [
      "name.secondName",
      "idNumber",
      "idType",
      "dob"
    ],
    "replyEndpoint": "https://raas-widgets-backend-sandbox.up.railway.app/partner/data-requests/dr_acme_x9y8z7w6v5u4",
    "expiresAt": "2026-07-23T15:30:00.000Z"
  }
}

Fulfill with:

curl -X PUT https://raas-widgets-backend-sandbox.up.railway.app/partner/data-requests/dr_acme_x9y8z7w6v5u4 \
  -H "X-API-Key: raas_sandbox_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "user_12345",
    "userData": {
      "idNumber": "GALO900515HDFRPN09",
      "idType": "CURP",
      "dob": "1990-05-15"
    }
  }'

Details: Data requests.

user.cip_verified

{
  "event": "user.cip_verified",
  "timestamp": "2026-07-30T14:40:00.000Z",
  "data": {
    "userId": "usr_a1b2c3d4e5f6g7h8",
    "referenceId": "user_12345",
    "cipStatus": "verified",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "ticketId": "tkt_abc123",
    "kentuckyStatus": "approved"
  }
}

CIP approved. No document or biometric PII is included — use GET /partner/users/:userId if you need CIP outcome detail. Also emitted: user.cip_failed (cipStatus: "failed") and user.cip_manual_review (cipStatus: "manual_review") with the same shape.

operation.created

{
  "event": "operation.created",
  "timestamp": "2026-07-23T14:30:00.000Z",
  "data": {
    "operationId": "op_a1b2c3d4e5f6",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "userId": "usr_x9y8z7w6v5u4",
    "requestId": "req_abc123",
    "status": "created",
    "funding": {
      "method": "card",
      "last4": "4242",
      "bankName": "visa"
    },
    "payout": {
      "method": "bank_account"
    },
    "amount": {
      "send": 100.0,
      "receive": 1850.5,
      "rate": 18.505,
      "fee": 3.99,
      "currency": {
        "send": "USD",
        "receive": "MXN"
      }
    },
    "createdAt": "2026-07-23T14:30:00.000Z"
  }
}

requestId is included only when the operation fulfills a money request (fund-request / Request API). Direct send operations omit it. Deferred payout claims include originationId instead.

After create, the operation moves through created → processing → a terminal status. See Operation lifecycle.

operation.completed

{
  "event": "operation.completed",
  "timestamp": "2026-07-28T12:00:00.000Z",
  "data": {
    "operationId": "op_a1b2c3d4e5f6",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "userId": "usr_x9y8z7w6v5u4",
    "requestId": "req_abc123",
    "status": "completed",
    "funding": {
      "method": "card"
    },
    "payout": {
      "method": "bank_account"
    },
    "amount": {
      "send": 100.0,
      "receive": 1850.5
    },
    "completedAt": "2026-07-28T12:00:00.000Z"
  }
}

Treat this as final success for fulfillment and reconciliation.

operation.failed

{
  "event": "operation.failed",
  "timestamp": "2026-07-28T12:05:00.000Z",
  "data": {
    "operationId": "op_a1b2c3d4e5f6",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "userId": "usr_x9y8z7w6v5u4",
    "requestId": "req_abc123",
    "status": "failed",
    "funding": {
      "method": "card"
    },
    "payout": {
      "method": "bank_account"
    },
    "amount": {
      "send": 100.0,
      "receive": 1850.5
    },
    "failedAt": "2026-07-28T12:05:00.000Z"
  }
}

If you held balances or locks on operation.created, reverse them when you receive operation.failed.

operation.cancelled

{
  "event": "operation.cancelled",
  "timestamp": "2026-07-23T14:35:00.000Z",
  "data": {
    "operationId": "op_a1b2c3d4e5f6",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "userId": "usr_x9y8z7w6v5u4",
    "status": "cancelled",
    "cancellationReason": "user_requested",
    "cancelledAt": "2026-07-23T14:35:00.000Z"
  }
}

Widget-initiated cancels may include referenceId and cancellationReason. Corridor-driven cancels include funding/payout/amount and may include requestId when the op fulfilled a money request. There is no separate operation.expired event — funding expiry maps to cancelled.

If you held balances or locks on operation.created, reverse them when you receive operation.cancelled.

request_money.created

Emitted after a successful legacy POST /v1/request-money. The platform creates a money request and a fund-request link for the sender.

{
  "event": "request_money.created",
  "timestamp": "2026-07-23T14:30:00.000Z",
  "data": {
    "legacyOperationReferenceId": "OpBnK001",
    "linkId": "link_acme_fund_req_01",
    "fundRequestLink": "https://<fund-request-host>/link_acme_fund_req_01",
    "landingLink": "https://app.example.com/pay?ref=OpBnK001",
    "waLink": "https://wa.me/…",
    "referenceId": "OpBnK001",
    "requestId": "req_abc123",
    "userReferenceId": "user-8842",
    "amount": 150.5,
    "currency": "GTQ",
    "status": "pending",
    "statusDetails": null
  }
}

Persist requestId and deliver fundRequestLink to the sender. Later operation.* events for the same ask include the same requestId. Full journey: Request money lifecycle.

request_money.failed

Emitted when a legacy Request API POST or GET under /v1/request-money fails (for example identity / watchlist rejection at create).

{
  "event": "request_money.failed",
  "timestamp": "2026-06-29T12:00:00.000Z",
  "data": {
    "path": "/v1/request-money",
    "method": "POST",
    "referenceId": "OpBnK001",
    "errorCode": "OFAC_HIT",
    "httpStatus": 403,
    "message": "Identity check rejected: global.watch.list.ofac",
    "details": {
      "restrictionKey": "global.watch.list.ofac"
    }
  }
}

request_money.updated is deprecated and not emitted. For payer fulfillment and settlement, use operation.created, operation.completed, operation.failed, and operation.cancelled.

deferred_payout.created

Emitted when a deferred payout origination is created (legacy deferred-payout API or first persistence in an awaiting-claim / payment-bound state).

{
  "event": "deferred_payout.created",
  "timestamp": "2026-07-23T14:30:00.000Z",
  "data": {
    "originationId": "dpr_abc123",
    "legacyReferenceId": null,
    "referenceId": "user-12345",
    "userReferenceId": "user-12345",
    "bindingState": "awaiting_claim",
    "payoutClaimLink": "https://<payout-claim-host>/link_…",
    "payoutClaimLinkId": "link_acme_claim_01",
    "operationId": null,
    "sendAmount": 100,
    "totalDebit": 103.5,
    "sendCurrency": "USD",
    "destinationCurrency": "MXN",
    "recipientHint": {
      "firstName": "Maria",
      "lastName": "Lopez"
    },
    "sourceCountry": "US",
    "destinationCountry": "MX"
  }
}

See Deferred payout.

deferred_payout.updated

Same payload shape as deferred_payout.created. Fired when binding state or operationId changes (claim, cancel, expire, or operation sync) after the initial create notification.

deferred_payout.failed

Structured error payload when a deferred payout API call fails (path, method, error code, HTTP status, message) — same pattern as request_money.failed.

Handler sketch

app.post('/webhooks/raas-widgets', async (req, res) => {
  // verify X-RAAS-Signature first, then:
  const { event, data } = JSON.parse(req.body.toString());
  res.status(200).send('OK');

  switch (event) {
    case 'link.created':
    case 'link.opened':
    case 'user.created':
    case 'user.role_added':
    case 'user.data_request':
    case 'user.cip_verified':
    case 'user.cip_failed':
    case 'user.cip_manual_review':
    case 'operation.created':
    case 'operation.completed':
    case 'operation.failed':
    case 'operation.cancelled':
    case 'request_money.created':
    case 'request_money.failed':
    case 'deferred_payout.created':
    case 'deferred_payout.updated':
    case 'deferred_payout.failed':
      await handle(event, data);
      break;
    default:
      console.log('Unknown event', event);
  }
});

Next steps

Security

Verify HMAC signatures.

Operation lifecycle

Statuses and which webhooks fire.

Request money lifecycle

Request → fund-request → operation.

Data requests

Fulfill user.data_request.

Getting Started

Request API

Concepts

Integration

Flows

Webhooks

Operations

Event types

link.created

link.opened

user.created

user.role_added

user.data_request

user.cip_verified

operation.created

operation.completed

operation.failed

operation.cancelled

request_money.created

request_money.failed

deferred_payout.created

deferred_payout.updated

deferred_payout.failed

Handler sketch

Next steps

Security

Operation lifecycle

Request money lifecycle

Data requests

​Event types

​link.created

​link.opened

​user.created

​user.role_added

​user.data_request

​user.cip_verified

​operation.created

​operation.completed

​operation.failed

​operation.cancelled

​request_money.created

​request_money.failed

​deferred_payout.created

​deferred_payout.updated

​deferred_payout.failed

​Handler sketch

​Next steps

Security

Operation lifecycle

Request money lifecycle

Data requests

Event types

link.created

link.opened

user.created

user.role_added

user.data_request

user.cip_verified

operation.created

operation.completed

operation.failed

operation.cancelled

request_money.created

request_money.failed

deferred_payout.created

deferred_payout.updated

deferred_payout.failed

Handler sketch

Next steps