Skip to main content

Events and payloads

POST{your webhook URL}
Auth Ryno-Signature

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​

FieldTypeNotes
iduuidThe event, equal to the Ryno-Event-Id header. The same on every retry and replay: your dedupe key.
typestringThe event name, equal to the Ryno-Event header.
specVersionstring1.0.
eventVersionintegerThe version of this event's data.
occurredAtdate-timeWhen it happened.
correlationobject{ "kind": "customer", "id": <customerId> } for the business and onboarding events. { "kind": "none", "id": "" } for the beneficiary events: read data.customerId instead.
dataobjectThe event's payload, below.

Events​

EventSent when
business.profile.createdA business customer is created by Create business profile.
business.profile.updatedUpdate business profile changed one or more profile fields.
business.person.addedA business person is created, at creation or by an update. One event per person.
business.document.confirmedA document is linked to the customer's pack by businessDocumentIdList. One event per document.
customer.onboarding.approvedThe business customer is approved: verificationStatus becomes Approved.
customer.onboarding.rejectedThe business customer is rejected: verificationStatus becomes Rejected.
customer.onboarding.changes_requestedCompliance needs more information: verificationStatus becomes ChangesRequested.
beneficiary.activatedA beneficiary's status becomes active: it can be paid.
beneficiary.rejectedA 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.profile.created and three business.person.added.

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 fieldTypeNotes
customerIduuidThe business customer.
partnerCustomerIdstringYour own id for this customer.
companyNamestringThe registered company name.
verificationStatusstringThe 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 fieldTypeNotes
customerIduuidThe business customer.
partnerCustomerIdstringYour own id for this customer.
companyNamestringThe name as it stands after the change.
verificationStatusstringThe status at the moment of the event.
changedFieldsarray of stringThe 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 fieldTypeNotes
customerIduuidThe business customer.
partnerCustomerIdstringYour own id for this customer.
uboIduuidThe person that was created.
firstNamestring
lastNamestring
emailstring
percentageShareinteger or nullOwnership 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 fieldTypeNotes
customerIduuidThe business customer.
partnerCustomerIdstringYour own id for this customer.
documentIduuidThe document you confirmed.
documentTypestringBusinessDocument. 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 fieldTypeNotes
customerIduuidThe business customer the decision is about.
businessIduuidIts business profile.
customerNamestringThe 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 fieldTypeNotes
customerIduuidThe business customer the decision is about.
businessIduuidIts business profile.
customerNamestringThe 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 fieldTypeNotes
customerIduuidThe business customer the decision is about.
businessIduuidIts business profile.
customerNamestringThe 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.activated and beneficiary.rejected 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 fieldTypeNotes
beneficiaryIduuidThe beneficiary.
customerIduuidIts owner, the same value Get beneficiary returns: your partner ID for your own beneficiary, or your customer's id.
currencystringThe currency the beneficiary receives, for example USD. The same value as currencyCode on the beneficiary.
countryCodestring or nullThe beneficiary's country, ISO 3166-1 alpha-3, for example CHN.
railstringHow the beneficiary is paid, for example RTGS.
labelstring or nullYour name for the beneficiary.
statusstringactive for beneficiary.activated, rejected for beneficiary.rejected.
messagestringbeneficiary.rejected only. Why it can't be paid and what to do next, in plain words. See below.
timestampdate-timeWhen 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:

messageWhat 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 }.