Events and payloads
ryno sends one POST to your registered URL for every event about your business customers and your beneficiaries. The body is JSON with the same envelope for every event; only data changes. Verify the signature before you trust it, and return any 2xx within 10 seconds.
Every partner receives every event. There is no subscription step, so a new event type starts arriving as soon as it ships: ignore a type you do not recognise rather than failing on it.
The envelope
| Field | Type | Notes |
|---|---|---|
id | uuid | The event, equal to the Ryno-Event-Id header. The same on every retry and replay: your dedupe key. |
type | string | The event name, equal to the Ryno-Event header. |
specVersion | string | 1.. |
eventVersion | integer | The version of this event's data. |
occurredAt | date-time | When it happened. |
correlation | object | { "kind": "customer", "id": <customerId> } for the business and onboarding events. { "kind": "none", "id": "" } for the beneficiary events: read data. instead. |
data | object | The event's payload, below. |
Events
| Event | Sent when |
|---|---|
business. | A business customer is created by Create business profile. |
business. | Update business profile changed one or more profile fields. |
business. | A business person is created, at creation or by an update. One event per person. |
business. | A document is linked to the customer's pack by businessDocumentIdList. One event per document. |
customer. | The business customer is approved: verificationStatus becomes Approved. |
customer. | The business customer is rejected: verificationStatus becomes Rejected. |
customer. | Compliance needs more information: verificationStatus becomes ChangesRequested. |
beneficiary. | A beneficiary's status becomes active: it can be paid. |
beneficiary. | A beneficiary's status becomes rejected: it can't be paid. |
A single call can raise several events: a create carrying three people sends one business. and three business..
Onboarding rejection reasons and reviewer notes are not in any payload. Read rejectionReason from Get verification status.
business.profile.created
A business customer is created by Create business profile.
data field | Type | Notes |
|---|---|---|
customerId | uuid | The business customer. |
partnerCustomerId | string | Your own id for this customer. |
companyName | string | The registered company name. |
verificationStatus | string | The status at the moment of the event, not necessarily now. |
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: business.profile.created
Ryno-Event-Id: 0f8c2b1e-6a4d-4c3b-9e2f-1a2b3c4d5e01
{
"id": "0f8c2b1e-6a4d-4c3b-9e2f-1a2b3c4d5e01",
"type": "business.profile.created",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-10-05T09:00:00.0000000+00:00",
"correlation": {
"kind": "customer",
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"data": {
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"partnerCustomerId": "acme-0001",
"companyName": "Acme Ltd",
"verificationStatus": "PendingVerification"
}
}
business.profile.updated
Update business profile changed one or more profile fields.
data field | Type | Notes |
|---|---|---|
customerId | uuid | The business customer. |
partnerCustomerId | string | Your own id for this customer. |
companyName | string | The name as it stands after the change. |
verificationStatus | string | The status at the moment of the event. |
changedFields | array of string | The fields the update supplied, named as you sent them, so you can react without diffing. |
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: business.profile.updated
Ryno-Event-Id: 1a9d3c2f-7b5e-4d4c-8f3a-2b3c4d5e6f02
{
"id": "1a9d3c2f-7b5e-4d4c-8f3a-2b3c4d5e6f02",
"type": "business.profile.updated",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-10-05T09:20:00.0000000+00:00",
"correlation": {
"kind": "customer",
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"data": {
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"partnerCustomerId": "acme-0001",
"companyName": "Acme Trading Ltd",
"verificationStatus": "PendingVerification",
"changedFields": [
"companyName",
"website"
]
}
}
business.person.added
A business person is created, at creation or by an update. One event per person.
data field | Type | Notes |
|---|---|---|
customerId | uuid | The business customer. |
partnerCustomerId | string | Your own id for this customer. |
uboId | uuid | The person that was created. |
firstName | string | |
lastName | string | |
email | string | |
percentageShare | integer or null | Ownership share, when the person holds one. |
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: business.person.added
Ryno-Event-Id: 2b0e4d3a-8c6f-4e5d-9a4b-3c4d5e6f7a03
{
"id": "2b0e4d3a-8c6f-4e5d-9a4b-3c4d5e6f7a03",
"type": "business.person.added",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-10-05T09:00:01.0000000+00:00",
"correlation": {
"kind": "customer",
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"data": {
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"partnerCustomerId": "acme-0001",
"uboId": "7c2a9e10-3b4d-4e5f-8a6b-1c2d3e4f5a6b",
"firstName": "Ada",
"lastName": "Obi",
"email": "ada.obi@acme.test",
"percentageShare": 60
}
}
business.document.confirmed
A document is linked to the customer's pack by businessDocumentIdList. One event per document.
data field | Type | Notes |
|---|---|---|
customerId | uuid | The business customer. |
partnerCustomerId | string | Your own id for this customer. |
documentId | uuid | The document you confirmed. |
documentType | string | BusinessDocument. A document uploaded as an identity document before 2026-10-27 may report UboIdentity. |
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: business.document.confirmed
Ryno-Event-Id: 3c1f5e4b-9d7a-4f6e-8b5c-4d5e6f7a8b04
{
"id": "3c1f5e4b-9d7a-4f6e-8b5c-4d5e6f7a8b04",
"type": "business.document.confirmed",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-10-05T09:45:00.0000000+00:00",
"correlation": {
"kind": "customer",
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"data": {
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"partnerCustomerId": "acme-0001",
"documentId": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f70",
"documentType": "BusinessDocument"
}
}
customer.onboarding.approved
The business customer is approved: verificationStatus becomes Approved.
data field | Type | Notes |
|---|---|---|
customerId | uuid | The business customer the decision is about. |
businessId | uuid | Its business profile. |
customerName | string | The registered company name. |
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: customer.onboarding.approved
Ryno-Event-Id: 4d2a6f5c-0e8b-4a7f-9c6d-5e6f7a8b9c05
{
"id": "4d2a6f5c-0e8b-4a7f-9c6d-5e6f7a8b9c05",
"type": "customer.onboarding.approved",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-10-06T14:10:00.0000000+00:00",
"correlation": {
"kind": "customer",
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"data": {
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"businessId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"customerName": "Acme Ltd"
}
}
customer.onboarding.rejected
The business customer is rejected: verificationStatus becomes Rejected.
data field | Type | Notes |
|---|---|---|
customerId | uuid | The business customer the decision is about. |
businessId | uuid | Its business profile. |
customerName | string | The registered company name. |
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: customer.onboarding.rejected
Ryno-Event-Id: 5e3b7a6d-1f9c-4b8a-8d7e-6f7a8b9c0d06
{
"id": "5e3b7a6d-1f9c-4b8a-8d7e-6f7a8b9c0d06",
"type": "customer.onboarding.rejected",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-10-06T14:10:00.0000000+00:00",
"correlation": {
"kind": "customer",
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"data": {
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"businessId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"customerName": "Acme Ltd"
}
}
customer.onboarding.changes_requested
Compliance needs more information: verificationStatus becomes ChangesRequested.
data field | Type | Notes |
|---|---|---|
customerId | uuid | The business customer the decision is about. |
businessId | uuid | Its business profile. |
customerName | string | The registered company name. |
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: customer.onboarding.changes_requested
Ryno-Event-Id: 6f4c8b7e-2a0d-4c9b-9e8f-7a8b9c0d1e07
{
"id": "6f4c8b7e-2a0d-4c9b-9e8f-7a8b9c0d1e07",
"type": "customer.onboarding.changes_requested",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-10-06T14:10:00.0000000+00:00",
"correlation": {
"kind": "customer",
"id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
},
"data": {
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"businessId": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
"customerName": "Acme Ltd"
}
}
Beneficiary events
beneficiary. and beneficiary. cover your own beneficiaries and your customers' beneficiaries. One beneficiary can send several. When each one fires, and when nothing is sent, is on Beneficiaries.
Both carry the same fields. No bank details are included: read the beneficiary with Get beneficiary for those.
data field | Type | Notes |
|---|---|---|
beneficiaryId | uuid | The beneficiary. |
customerId | uuid | Its owner, the same value Get beneficiary returns: your partner ID for your own beneficiary, or your customer's id. |
currency | string | The currency the beneficiary receives, for example USD. The same value as currencyCode on the beneficiary. |
countryCode | string or null | The beneficiary's country, ISO 3166-1 alpha-3, for example CHN. |
rail | string | How the beneficiary is paid, for example RTGS. |
label | string or null | Your name for the beneficiary. |
status | string | active for beneficiary., rejected for beneficiary.. |
message | string | beneficiary. only. Why it can't be paid and what to do next, in plain words. See below. |
timestamp | date-time | When the status changed, in UTC. |
beneficiary.activated
A beneficiary's status becomes active. It can now be paid.
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: beneficiary.activated
Ryno-Event-Id: 7a5d9c8f-3b1e-4d0c-8f9a-8b9c0d1e2f08
{
"id": "7a5d9c8f-3b1e-4d0c-8f9a-8b9c0d1e2f08",
"type": "beneficiary.activated",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-11-16T10:42:08.0000000+00:00",
"correlation": {
"kind": "none",
"id": ""
},
"data": {
"beneficiaryId": "1d7f3b9a-2e6c-4a85-9f10-6b3c8e2d4a71",
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"currency": "USD",
"countryCode": "CHN",
"rail": "RTGS",
"label": "Acme main supplier",
"status": "active",
"timestamp": "2026-11-16T10:42:07.512345Z"
}
}
beneficiary.rejected
A beneficiary's status becomes rejected. It can't be paid. message says why and what to do, and is one of:
message | What to do |
|---|---|
| This beneficiary can't be paid for this customer. Editing it won't change that, so disable it instead. | Disable the beneficiary. An edit leaves it rejected. |
| This beneficiary has been suspended and can't be paid. Contact support. | Contact support. |
| These beneficiary details were not accepted. Check them and edit the beneficiary to send it for review again. | Correct the address, city, website or documents with Update beneficiary. If the account details were wrong, disable it and create a new beneficiary. |
Show message to your users as it is, and don't parse it: the wording may change. More messages may be added.
POST {your webhook URL}
Content-Type: application/json
Ryno-Event: beneficiary.rejected
Ryno-Event-Id: 8b6e0d9a-4c2f-4e1d-9a0b-9c0d1e2f3a09
{
"id": "8b6e0d9a-4c2f-4e1d-9a0b-9c0d1e2f3a09",
"type": "beneficiary.rejected",
"specVersion": "1.0",
"eventVersion": 1,
"occurredAt": "2026-11-16T10:42:08.0000000+00:00",
"correlation": {
"kind": "none",
"id": ""
},
"data": {
"beneficiaryId": "1d7f3b9a-2e6c-4a85-9f10-6b3c8e2d4a71",
"customerId": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
"currency": "USD",
"countryCode": "CHN",
"rail": "RTGS",
"label": "Acme main supplier",
"status": "rejected",
"message": "These beneficiary details were not accepted. Check them and edit the beneficiary to send it for review again.",
"timestamp": "2026-11-16T10:42:07.512345Z"
}
}
webhook.test
Sent only when someone in your organisation sends a test event from the Partner Portal, so you can prove your receiver end to end. data is { "message": string, "occurredAtUtc": date-time, "isTestFire": true }.