Webhook events

Event types

Event	Description
`link.created`	A magic link was created
`link.opened`	User opened a magic link
`link.cancelled`	User cancelled the widget before creating an operation (link stays active)
`link.reuse_blocked`	A second payment was attempted on a single-use (Lola) link
`user.created`	End-user record first created for a `referenceId`
`user.role_added`	First time the user participated as `sender`, `receiver`, or `claimer`
`user.campaign_attributed`	First-touch campaign slug stamped on the user
`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.references_available`	Canonical refs (pickup PIN, tracking) landed on the operation
`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.

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",
    "campaign": "feb-promo-gt"
  }
}

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"
    }
  }
}

link.cancelled

Emitted when the end user cancels the widget before creating an operation (for example the Lola summary Cancel). The link is not revoked: the same URL remains claimable until TTL. Distinct from operation.cancelled (Reg E, after create) and from partner POST /partner/links/:id/revoke.

{
  "event": "link.cancelled",
  "timestamp": "2026-09-05T12:00:00.000Z",
  "data": {
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "wa:+15551234567",
    "flow": "lola",
    "cancelledAt": "2026-09-05T12:00:00.000Z",
    "reason": "user_cancel"
  }
}

A second cancel re-emits the same event. Dedupe by linkId (and a short window) if you prompt the user. Do not treat the link as dead.

link.reuse_blocked

Emitted when a single-use magic link (today: Lola) already created an operation and the widget attempts POST /widget/links/:linkId/operations again. The HTTP response is 409 LINK_ALREADY_USED. Distinct from link.cancelled (cancel before create) and from operation.cancelled. The consumed link stays claimable (HTTP 200) so the customer can see the payment reference and return to chat. Do not treat this as a dead link. Offer a new Lola link if they need to send again.

{
  "event": "link.reuse_blocked",
  "timestamp": "2026-09-06T18:05:00.000Z",
  "data": {
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "wa:+15551234567",
    "flow": "lola",
    "consumedOperationId": "op_abc123",
    "attemptedAt": "2026-09-06T18:05:00.000Z"
  }
}

Other flows do not emit this event: their magic links stay unlimited.

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), receiver (minted a money request), or claimer (completed a payout-claim bind). Optional correlation fields: operationId, requestId, originationId, linkId. Roles are additive history, not entitlements — they do not skip CIP.

user.campaign_attributed

Fired the first time a campaign slug is stamped on a user (typically on magic-link claim). Later links with other slugs only append to campaignsParticipated and do not re-emit this event. The first-touch campaign is immutable.

{
  "event": "user.campaign_attributed",
  "timestamp": "2026-09-08T14:30:00.000Z",
  "data": {
    "userId": "usr_a1b2c3d4e5f6g7h8",
    "referenceId": "user_12345",
    "campaign": "feb-promo-gt",
    "campaignFirstSeenAt": "2026-09-08T14:30:00.000Z",
    "campaignsParticipated": ["feb-promo-gt"],
    "linkId": "link_acme_a1b2c3d4e5f6"
  }
}

campaign is an opaque slug. Sponsor, dates, and revenue terms live in your campaign system — join on this key.

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": "clerk_2n8kQxPayer",
    "recipientReferenceId": "user-8842",
    "userId": "usr_x9y8z7w6v5u4",
    "requestId": "req_abc123",
    "campaign": "feb-promo-gt",
    "campaignSource": "link",
    "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. When the receiving party is a known User (request fulfillment or payout-claim), recipientReferenceId is that party’s partner User.referenceId (for Request API: requestData.userReferenceId). referenceId remains the funding party. recipientUserId is not sent to partners.

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",
    "referenceId": "clerk_2n8kQxPayer",
    "recipientReferenceId": "user-8842",
    "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. referenceId is the partner identity of userId (same value as operation.created and GET /partner/operations/:id). Do not assume this payload already contains the pickup PIN. The PIN is a separate payout code delivery (operation.references_available and/or GET /partner/operations/:id).

operation.references_available

Fired when the corridor has issued canonical references for an in-flight or recently settled operation (pickup PIN, tracking ref). Does not change status.

{
  "schemaVersion": 1,
  "event": "operation.references_available",
  "timestamp": "2026-08-27T06:40:00.000Z",
  "data": {
    "operationId": "op_a1b2c3d4e5f6",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "userId": "usr_x9y8z7w6v5u4",
    "status": "processing",
    "references": [
      {
        "type": "PAYOUT_CODE",
        "value": "998877",
        "presentation": "PROMINENT"
      }
    ],
    "documents": [
      {
        "kind": "PAYOUT_RECEIPT",
        "mediaType": "application/pdf",
        "freshness": "LIVE",
        "availability": "AVAILABLE"
      }
    ]
  }
}

The PIN is references where type === "PAYOUT_CODE". Integration guide: Payout code (PIN).

Document descriptors may appear on this event. PDF bytes are never attached — download via GET /partner/operations/:id/documents/PAYOUT_RECEIPT.

operation.failed

{
  "event": "operation.failed",
  "timestamp": "2026-07-28T12:05:00.000Z",
  "data": {
    "operationId": "op_a1b2c3d4e5f6",
    "linkId": "link_acme_a1b2c3d4e5f6",
    "referenceId": "user_12345",
    "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"
  }
}

Terminal operation.* events include referenceId of the operation’s user (same value as operation.created). Widget-initiated cancels also include 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.cancelled

Emitted once per pending request when the requester is blocked. The request is cancelled and its shareable fund-request link is revoked. Requests with an operation already created are left unchanged.

{
  "event": "request_money.cancelled",
  "timestamp": "2026-09-02T13:20:00.000Z",
  "data": {
    "requestId": "req_abc123",
    "referenceId": "user-8842",
    "status": "cancelled",
    "reason": "USER_BLOCKED",
    "fundRequestLinkId": "link_acme_fund_req_01",
    "fundRequestLinkRevoked": true,
    "cancelledAt": "2026-09-02T13:20:00.000Z"
  }
}

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 'link.cancelled':
    case 'link.reuse_blocked':
    case 'user.created':
    case 'user.campaign_attributed':
    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.references_available':
    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.

Payout code (PIN)

Pickup PIN via GET or webhook.

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

link.cancelled

link.reuse_blocked

user.created

user.role_added

user.campaign_attributed

user.data_request

user.cip_verified

operation.created

operation.completed

operation.references_available

operation.failed

operation.cancelled

request_money.created

request_money.cancelled

request_money.failed

deferred_payout.created

deferred_payout.updated

deferred_payout.failed

Handler sketch

Next steps

Security

Operation lifecycle

Payout code (PIN)

Request money lifecycle

Data requests

​Event types

​link.created

​link.opened

​link.cancelled

​link.reuse_blocked

​user.created

​user.role_added

​user.campaign_attributed

​user.data_request

​user.cip_verified

​operation.created

​operation.completed

​operation.references_available

​operation.failed

​operation.cancelled

​request_money.created

​request_money.cancelled

​request_money.failed

​deferred_payout.created

​deferred_payout.updated

​deferred_payout.failed

​Handler sketch

​Next steps

Security

Operation lifecycle

Payout code (PIN)

Request money lifecycle

Data requests

Event types

link.created

link.opened

link.cancelled

link.reuse_blocked

user.created

user.role_added

user.campaign_attributed

user.data_request

user.cip_verified

operation.created

operation.completed

operation.references_available

operation.failed

operation.cancelled

request_money.created

request_money.cancelled

request_money.failed

deferred_payout.created

deferred_payout.updated

deferred_payout.failed

Handler sketch

Next steps