Overview#
To meet KuCoin's updated requirements for Webhook integration, we have introduced a redesigned Webhook management platform, providing brokers with a more standardized and streamlined integration experience.This Webhook is used to notify Exchange Brokers of the KYC verification results of their sub-accounts.To ensure seamless integration, brokers are required to provide API endpoints that comply with KuCoin's request and response specifications for system integration and callback handling. Brokers can configure and manage their Webhook URLs directly through the Webhook Settings page on the management platform.Existing Webhook integrations will continue to function as usual. However, brokers are strongly encouraged to migrate to the new Webhook integration as soon as possible to ensure compatibility with KuCoin's updated requirements and benefit from the enhanced management experience.Pre-integration Setup#
Before starting the integration, please contact your account manager to confirm your webhook integration requirements and request access to the Webhook Settings Page.
For assistance, you may also contact us via Telegram: @KuCoin_Broker_Grace.Once access has been granted, log in to the Webhook Settings Page and submit your Webhook URL (Notify URL).
Please ensure that your Webhook URL meets the following requirements:Protocol: Must support HTTP or HTTPS.
Accessibility: Must be publicly accessible over the internet.
Uniqueness: Each Webhook URL must be unique.
Length: Must not exceed 512 characters.
3. Secure Your Webhook Key#
After submitting your Webhook URL application, a corresponding Key will be generated. This Key is used to verify the authenticity of webhook callback requests.
Please note:The Webhook Key will only be displayed once upon generation.
Make sure to securely save the Webhook Key immediately after it is generated.
Each Webhook URL is associated with one exclusive Key.
Do not share your Webhook Key with unauthorized parties.
4. Wait for Webhook URL Approval#
After submission, KuCoin will review your Webhook URL. The approval process typically takes 1–2 business days.
Please note that applications may be rejected if the submitted URL does not meet KuCoin's requirements. In such cases, you will need to submit a new Webhook URL for review.Integration Process#
5. Prepare for Integration#
After submitting your Webhook URL, please ensure that your callback service is ready for integration.
Your API service should be capable of:Receiving webhook callback requests from KuCoin.
Verifying the authenticity of incoming requests using the Webhook Key.
Processing and handling KYC verification result notifications.
Returning responses in accordance with KuCoin's standard response structure.
Please ensure that your callback service is properly configured and ready for testing before proceeding to the next step.
6. KuCoin Completes the API Integration#
Once your Webhook URL has been approved and your callback service is ready, KuCoin will proceed with the necessary API integration and callback configuration.7. Receive KYC Verification Results#
Once the integration is completed, KuCoin will automatically send webhook callback notifications containing the relevant KYC verification results to your configured Webhook URL when the corresponding KYC review is completed.
Please ensure that your endpoint can correctly receive and process these callback requests.8. Callback Retry Policy#
KuCoin does not automatically retry failed webhook callback requests.
If a callback delivery fails, the system will not automatically resend the request.
Therefore, brokers are responsible for ensuring that their callback services remain stable and are capable of receiving and processing webhook notifications successfully.Secret Management#
9. Reset Your Webhook Key#
If you need to reset your Webhook Key, navigate to the Webhook Settings Page and click Reset.
Please be aware that once the Webhook Key is reset:The previously generated Webhook Key will immediately become invalid.
You must update your integration configuration with the new Key.
All subsequent webhook callback requests must be verified using the new Key.
Make sure to update your Webhook Key promptly to avoid callback verification failures.
URL#
| URI | Interface method |
|---|
| Any URL that is in a valid format and publicly accessible over the internet,Supports HTTP and HTTPS. | POST |
Message#
| header | Description | Example |
|---|
| Authorization | Bearer 〈 The key generated by this platform 〉 | Bearer 82cf0f9ce17e4f70a0f8552bdc4824ea |
HTTP BODY#
| header | Type | Description | Example |
|---|
| X-Trace | String | The trace ID is used for troubleshooting. It is recommended to log it when writing logs. | c570e2de550b4b5383995a14b38dd159 |
| X-Body | Object | The business message body is an object. | {"clientUid": 240001,"rejectReason": "SUMSUB_REJECT","result": "REJECT"} |
Your API Response#
Currently, HTTP 200 is considered a success, and all other statuses are considered failures.Modified at 2026-11-17 02:49:05