Account & KYC Webhooks

Event Types

Event Type	Description
`account_created`	A new account has been created
`account_status_updated`	The account status has changed
`kyc_status_updated`	The KYC verification status has changed
`kyc_needs_update`	Additional KYC information is required
`bank_account_link`	Bank account linking status has changed
`kyc_verification_submitted`	A KYC verification was submitted for review
`kyc_verification_signed`	The applicant signed the verification agreement
`kyc_document_uploaded`	Documents were uploaded for a KYC verification
`kyc_document_upload_received`	The verification provider acknowledged a document
`kyc_verification_completed`	A KYC verification reached a final outcome
`kyb_verification_submitted`	A business verification was submitted for review
`kyb_document_uploaded`	A document was uploaded for a business verification

Account Events

Account Created

Triggered when a new account is created in the system.

Details Schema

Field	Type	Description
`accountId`	string	Unique account identifier (UUID)
`status`	string	Account status. One of: `pending`, `active`, `paused`, `closed`
`accountType`	string	Account type (e.g., `individual`, `business`)
`email`	string	Account email address
`reference`	string	Account reference identifier

Sample Payload

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "account_created",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "accountId": "00000000-0000-0000-0000-000000000000",
        "status": "pending",
        "accountType": "individual",
        "email": "user@example.com",
        "reference": "REF-123456"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

Account Status Updated

Triggered when an account's status changes (e.g., from pending to active after KYC approval).

Details Schema

Field	Type	Description
`accountId`	string	Unique account identifier (UUID)
`status`	string	New account status. One of: `pending`, `active`, `paused`, `closed`
`previousStatus`	string	Previous account status
`accountType`	string	Account type (e.g., `individual`, `business`)
`email`	string	Account email address
`reference`	string	Account reference identifier

Sample Payload

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "account_status_updated",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "accountId": "00000000-0000-0000-0000-000000000000",
        "status": "active",
        "previousStatus": "pending",
        "accountType": "individual",
        "email": "user@example.com",
        "reference": "REF-123456"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

Account Statuses

Status	Description
`pending`	Account is awaiting KYC verification
`active`	Account is fully verified and active
`paused`	Account is temporarily paused (e.g., KYC needs update)
`closed`	Account has been closed (e.g., KYC rejected)

KYC Events

KYC Status Updated

Triggered when a KYC verification status changes.

Details Schema

Field	Type	Description
`kycId`	string	Unique KYC record identifier (UUID)
`accountId`	string	Associated account identifier (UUID)
`status`	string	New KYC status. One of: `pending`, `in_review`, `approved`, `needs_update`, `rejected`
`previousStatus`	string	Previous KYC status
`statusReason`	string	Reason for the status change (may be empty)
`kycType`	string	Type of KYC verification. One of: `card`, `banking`

Sample Payload

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "kyc_status_updated",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "kycId": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "status": "approved",
        "previousStatus": "in_review",
        "statusReason": "",
        "kycType": "banking"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

KYC Needs Update

Triggered when additional KYC information or documentation is required. This is a specific case of kyc_status_updated where the status transitions to needs_update.

Details Schema

Same schema as KYC Status Updated.

Sample Payload

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "kyc_needs_update",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "kycId": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "status": "needs_update",
        "previousStatus": "in_review",
        "statusReason": "Additional documentation required",
        "kycType": "banking"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

KYC Statuses

Status	Description
`pending`	KYC verification has not started
`in_review`	KYC verification is being reviewed
`approved`	KYC verification has been approved
`needs_update`	Additional information or documentation is required
`rejected`	KYC verification has been rejected

KYC Types

Type	Description
`card`	Card verification
`banking`	Banking verification

Bank Account Link

Triggered when a bank account linking status changes.

Details Schema

Field	Type	Description
`accountLastFour`	string	Last four digits of the bank account
`status`	string	Bank account link status
`statusReason`	string	Reason for the status

Sample Payload

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "bank_account_link",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "accountLastFour": "1234",
        "status": "active",
        "statusReason": "Bank account linked successfully"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

KYC Verification Events

kycType is banking or card, identifying which verification the event belongs to. Every one of these carries kycId and accountId.

KYC Verification Submitted

Sent when a verification is handed to the provider for review.

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "kyc_verification_submitted",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "kycId": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "status": "in_review",
        "previousStatus": "pending"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

KYC Verification Signed

Sent when the applicant accepts the terms and signs. signedVia records the channel used.

Field	Type	Description
`kycId`	string	KYC record identifier (UUID)
`accountId`	string	Associated account identifier (UUID)
`kycType`	string	`banking` or `card`
`signedAt`	string	When the agreement was signed (ISO 8601)
`signedVia`	string	Channel the signature came through
`termsAndConditionsAcceptedAt`	string	When the terms were accepted (ISO 8601)
`privacyPolicyAcceptedAt`	string	When the privacy policy was accepted (ISO 8601)

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "kyc_verification_signed",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "kycId": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "kycType": "banking",
        "signedAt": "2025-01-01T00:00:00Z",
        "signedVia": "dashboard",
        "termsAndConditionsAcceptedAt": "2025-01-01T00:00:00Z",
        "privacyPolicyAcceptedAt": "2025-01-01T00:00:00Z"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

KYC Document Uploaded

Sent when documents are uploaded. files is an array — one event can cover several documents.

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "kyc_document_uploaded",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "kycId": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "kycType": "banking",
        "files": [
            { "key": "kyc/00000000/passport.jpg", "size": 248311, "contentType": "image/jpeg" }
        ]
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

KYC Document Upload Received

Sent when the verification provider acknowledges a document. This is the provider's confirmation, distinct from your upload succeeding.

Field	Type	Description
`kycId`	string	KYC record identifier (UUID)
`accountId`	string	Associated account identifier (UUID)
`kycType`	string	`banking` or `card`
`document`	string	The document the provider acknowledged
`event`	string	The provider's event name
`occurredAt`	string	When the provider recorded it (ISO 8601)

KYC Verification Completed

Sent when a verification reaches a final outcome. Read the account's current status through the API rather than inferring it here.

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "kyc_verification_completed",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "kycId": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "kycType": "banking",
        "completedAt": "2025-01-01T00:00:00Z"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

KYB Events

Business verification. See the KYB Guide for the process these events report on.

KYB Verification Submitted

Field	Type	Description
`kybId`	string	KYB record identifier (UUID)
`accountId`	string	Associated account identifier (UUID)
`status`	string	Verification status
`statusReason`	string	Reason for the status, when there is one
`entityType`	string	Legal entity type — see Supported Entity Types

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "kyb_verification_submitted",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "kybId": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "status": "in_review",
        "entityType": "limited_liability_company"
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

KYB Document Uploaded

Sent once per document, carrying that single file.

{
    "webhookId": "00000000-0000-0000-0000-000000000000",
    "type": "kyb_document_uploaded",
    "accountId": "00000000-0000-0000-0000-000000000000",
    "timestamp": "2025-01-01T00:00:00Z",
    "details": {
        "kybId": "00000000-0000-0000-0000-000000000000",
        "accountId": "00000000-0000-0000-0000-000000000000",
        "file": { "key": "kyb/00000000/certificate.pdf", "size": 118204, "contentType": "application/pdf" }
    },
    "systemNotes": "Do not rely solely on this webhook for final state. Always verify the current status via the API to ensure consistency. Consult the developer documentation and guides for more information."
}

Support and Resources

If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.

Stay Updated

Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:

Instagram: BlockWyre Instagram
Twitter: BlockWyre Twitter
Facebook: BlockWyre Facebook
LinkedIn: BlockWyre LinkedIn

We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!

Event Types​

Account Events​

Account Created​

Details Schema​

Sample Payload​

Account Status Updated​

Details Schema​

Sample Payload​

Account Statuses​

KYC Events​

KYC Status Updated​

Details Schema​

Sample Payload​

KYC Needs Update​

Details Schema​

Sample Payload​

KYC Statuses​

KYC Types​

Bank Account Link​

Details Schema​

Sample Payload​

KYC Verification Events​

KYC Verification Submitted​

KYC Verification Signed​

KYC Document Uploaded​

KYC Document Upload Received​

KYC Verification Completed​

KYB Events​

KYB Verification Submitted​

KYB Document Uploaded​

Support and Resources​

Stay Updated​

Event Types

Account Events

Account Created

Details Schema

Sample Payload

Account Status Updated

Details Schema

Sample Payload

Account Statuses

KYC Events

KYC Status Updated

Details Schema

Sample Payload

KYC Needs Update

Details Schema

Sample Payload

KYC Statuses

KYC Types

Bank Account Link

Details Schema

Sample Payload

KYC Verification Events

KYC Verification Submitted

KYC Verification Signed

KYC Document Uploaded

KYC Document Upload Received

KYC Verification Completed

KYB Events

KYB Verification Submitted

KYB Document Uploaded

Support and Resources

Stay Updated