Corporates

Corporate beneficiary status update

Sent when the verification status or details of a corporate beneficiary change. A beneficiary is a director, UBO, shareholder, or partner whose own verification feeds into the corporate's KYB outcome.

Use it to prompt a beneficiary for a fresh document before identityRestrictionDate passes and the corporate is restricted, rather than waiting for the KYB status itself to regress.

Enable and configure webhooks in the Embedder Portal; recent events are listed on its Webhook Logs page. Weavr sends this event to {Webhook URL}/corporates/kyb/beneficiaries/watch.

postWebhook/corporates/kyb/beneficiaries/watch

Headers

call-refstring

A call reference generated by the caller and unique to the caller to provide correlation between the caller and system with a maximum length of 255

published-timestampinteger required

The timestamp, expressed in Epoch timestamp using millisecond precision, when this event was published.

signaturestring required

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the published-timestamp using your API key.

signature-v2string required

The signature to verify the authenticity of this request. This is the base64 hash (HmacSHA256) of the call-ref + payload + published-timestamp using your API key.

Payload

eventCorporateBeneficiaryEventType[]

What changed on the beneficiary. Each entry names the field that triggered the event followed by the action that occurred.

eventDetailsCorporateKybFailureReason[]

Reasons, if any, describing why the event occurred.

rejectionCommentstring

Reason shown to the user after a temporary rejection.

Example payload

{
  "additionalInformation": {
    "corporateId": "123456789",
    "corporateName": "Acme Ltd",
    "rootUserEmail": "alex.smith@example.com",
    "beneficiary": {
      "firstName": "Alex",
      "middleName": "Jordan",
      "lastName": "Smith",
      "email": "alex.smith@example.com"
    },
    "documentExpiryDate": "1786118400000",
    "identityRestrictionDate": "1786118400000"
  }
}

Response

Event received.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.