KYC Events

You can expect to receive KYC webhook events whenever you update a user’s KYC data, submit KYC to unlock a rail, or receive KYC status updates for any rail you’ve submitted.

Types

• KYC.DATA.UPDATE: Updates to the user’s KYC data.
• KYC.STATUS.CREATE: Submission of the user’s KYC status for any rail.
• KYC.STATUS.UPDATE: Update of the user’s KYC status for any rail.
• KYC_LINK.CREATE: Creation of a KYC Link.
• KYC_LINK.UPDATE: Submission of a KYC Link.
• KYC.RFI.OPEN: An onboarding request for information (RFI) was issued.
• KYC.RFI.CLOSED: The user’s onboarding RFI was resolved or expired.

KYC.DATA

The data object is expected to have the same structure as the response from the Get KYC Data endpoint.

{
  "eventId": "evt_19571191645da9be1",
  "eventCategory": "KYC",
  "eventType": "KYC.DATA.UPDATE",
  "eventAction": "UPDATE",
  "data": {
    "userId": "c5a11cdb-2696-4a2e-ac58-3e17fb230288",
    "kycInfo": {
      "type": "individual",
      "email": "[e-mail]",
      "phone": null,
      "idType": null,
      "address": {
        "city": "New York",
        "country": "USA",
        "postalCode": "12345",
        "addressLine1": "123 Main St.",
        "stateProvinceRegion": "NY"
      },
      "purpose": null,
      "idNumber": null,
      "lastName": "Yang",
      "firstName": "William",
      "govIdType": null,
      "ipAddress": null,
      "middleName": null,
      "dateOfBirth": "2000-01-16T00:00:00+00:00",
      "govIdNumber": null,
      "nationality": null,
      "govIdBackUrl": null,
      "govIdCountry": null,
      "govIdFrontUrl": null,
      "lastNameLocal": null,
      "countryOfBirth": null,
      "firstNameLocal": null,
      "middleNameLocal": null,
      "additionalIdType": null,
      "govIdHandHoldUrl": null,
      "supplementaryUrl": null,
      "govIdIssuanceDate": null,
      "proofOfAddressUrl": null,
      "supplementaryInfo": null,
      "additionalIdNumber": null,
      "proofOfAddressType": null,
      "sofEuQuestionnaire": null,
      "govIdExpirationDate": null,
      "govIdIssuanceAuthority": null,
      "productServiceCategory": null,
      "taxIdentificationNumber": null
    }
  },
  "createdAt": "2025-03-07T14:53:44.443Z",
  "timestamp": "2025-03-07T14:54:00.326Z",
  "version": "v2"
}

KYC.STATUS

The data object is expected to have the same structure as the response from the Get KYC Status endpoint.

{
  "eventId": "evt_195711af0545510a78",
  "eventCategory": "KYC",
  "eventType": "KYC.STATUS.CREATE",
  "eventAction": "CREATE",
  "data": {
    "userId": "c5a11cdb-2696-4a2e-ac58-3e17fb230288",
    "SOUTH_AMERICA_LIGHT": {
      "limit": {},
      "onRamp": {
        "brl": {
          "pix": {
            "status": "PENDING",
            "message": "",
            "warnings": []
          }
        }
      },
      "status": "PENDING",
      "message": "",
      "offRamp": {
        "ars": {
          "transfers": {
            "status": "PENDING",
            "message": "",
            "warnings": []
          }
        },
        "brl": {
          "pix": {
            "status": "PENDING",
            "message": "",
            "warnings": []
          }
        },
        "cop": {
          "achCop": {
            "status": "PENDING",
            "message": "",
            "warnings": []
          }
        },
        "mxn": {
          "spei": {
            "status": "PENDING",
            "message": "",
            "warnings": []
          }
        }
      },
      "warnings": []
    }
  },
  "createdAt": "2025-03-07T14:55:45.780Z",
  "timestamp": "2025-03-07T14:56:00.355Z",
  "version": "v2"
}

KYC.RFI

Sent when an onboarding request for information opens or closes. The data object has the same structure as KYC.STATUS for the USD rail, including its rfi object. On KYC.RFI.OPEN, rfi describes the open request. On KYC.RFI.CLOSED, it is null.

Transaction RFIs are sent as ONRAMP.RFI.* and OFFRAMP.RFI.* instead. See Onramp Events and Offramp Events.

{
  "eventId": "evt_19a3c7f2b1e94d0c55",
  "eventCategory": "KYC",
  "eventType": "KYC.RFI.OPEN",
  "eventAction": "OPEN",
  "data": {
    "userId": "2d5b7e18-9c40-4a63-b8f1-7e0a4c9d2536",
    "USD": {
      "status": "RFI_PENDING",
      "message": "",
      "reviewResult": {},
      "details": {
        "personalInfo": {
          "reviewResult": {}
        }
      },
      "rfi": {
        "id": "7c9e1a34-5b02-4d68-91af-3e6d2b8c4075",
        "kind": "onboarding",
        "status": "issued",
        "subjectType": "individual",
        "userId": "2d5b7e18-9c40-4a63-b8f1-7e0a4c9d2536",
        "transferId": null,
        "flowType": null,
        "createdAt": "2026-07-01T10:30:00.000Z",
        "currentRound": 1,
        "round": {
          "id": "b81d4f2c-6e35-4a90-9f27-0c3e5a71d8b6",
          "round": 1,
          "issuedAt": "2026-07-01T10:30:00.000Z",
          "expiresAt": "2026-07-31T10:30:00.000Z",
          "submittedAt": null,
          "items": [
            {
              "id": "3f7c1e90-2a4b-4d61-9c0e-5b8f2d6a1e34",
              "kind": "document",
              "label": "Proof of address issued in the last 3 months",
              "docType": "proof_of_address",
              "detail": "A utility bill or bank statement dated within the last three months.",
              "required": true
            }
          ],
          "link": "https://dashboard.hifi.com/production/rfi-link/rfir_2mNpXwZ7bV1aLcs3Kf9dQ#sessionToken=..."
        }
      }
    }
  },
  "createdAt": "2026-07-01T10:30:01.120Z",
  "timestamp": "2026-07-01T10:30:15.402Z",
  "version": "v2"
}

KYC_LINK.CREATE

This webhook event will be emitted upon KYC Link creation by the developer.

{
  "data": {
    "id": "ec3da5dc-d498-4034-aefc-5f51e589f15f",
    "rails": ["ON_CHAIN"],
    "valid": true,
    "userId": null,
    "userType": "individual",
    "createdAt": "2025-04-29T01:58:35.56784+00:00",
    "expiredAt": "2025-05-04T01:58:35.528+00:00",
    "templateId": "2fb2da24-472a-4e5b-b160-038d9dc82a40",
    "redirectUrl": null,
    "sessionToken": "ec9d38de822864bb34d4e68f8466487afb31bf0d015e9c4d2d1bf80f4f67f4764316e8f5f05a30c7a312b11b36d5"
  },
  "eventId": "evt_1967f4477811e8fa82",
  "version": "v2",
  "createdAt": "2025-04-29T01:58:35.689Z",
  "eventType": "KYC_LINK.CREATE",
  "timestamp": "2025-04-29T01:58:40.235Z",
  "eventAction": "CREATE",
  "eventCategory": "KYC_LINK"
}

KYC_LINK.UPDATE

This webhook event will be emitted upon KYC Link Submission via the hosted page by the end-user.

{
  "data": {
    "id": "ec3da56c-d498-4034-aefc-5f51e589f15f",
    "rails": ["ON_CHAIN"],
    "valid": false,
    "userId": "857e9b69-a629-4e86-9cf3-ec4bcf2e38b4",
    "userType": "individual",
    "createdAt": "2025-04-29T01:58:35.56784+00:00",
    "expiredAt": "2025-05-04T01:58:35.528+00:00",
    "templateId": "2fb2da24-472a-4e5b-b160-038d9dc82a40",
    "redirectUrl": null,
    "sessionToken": "ec9d38de822864bb34d48466487afb31bf0d015e9c4d2d1bf80f4f67f4764316e8f5f05a30c7a312b11b36d5"
  },
  "eventId": "evt_1967f45caef15027c0",
  "version": "v2",
  "createdAt": "2025-04-29T02:00:02.586Z",
  "eventType": "KYC_LINK.UPDATE",
  "timestamp": "2025-04-29T02:00:20.440Z",
  "eventAction": "UPDATE",
  "eventCategory": "KYC_LINK"
}