WaaS Webhook Callback Mechanism
Receiving, response, signature verification, and idempotency rules for WaaS callbacks.
Understand Cregis event delivery rules, including callback reception standards and anti-spoofing signature verification.
Why Asynchronous Callbacks
Because blockchain confirmation and Cregis risk-control review are asynchronous and can take unpredictable time, core capital operations (such as WaaS deposits, business payouts, and payment-engine order settlement) rely on Webhook / Callback as the final source of business truth. Compared with long-running HTTP polling, callbacks significantly reduce server I/O overhead.
When creating business addresses or submitting payout requests, you can explicitly define the receiving endpoint through callback_url. When status changes occur (for example, on-chain confirmation), Cregis will proactively push notifications to that URL.
Receiving & Response Rules
- Request format: POST application/json
- Success acknowledgement: after your system receives and processes the callback, your endpoint must return HTTP 200 and the response body must strictly equal success (plain text only, no additional content). Any other status code (such as 404/500) or any non-exact response body is treated as callback failure.
Success and Failure Examples
Successful response example: after signature verification, idempotency checks, and business processing all pass, return HTTP 200 with plain-text success.
HTTP/1.1 200 OK
Content-Type: text/plain
successFailure examples: the following response bodies contain success but are not exactly plain-text success, so they are not treated as successful acknowledgements. Any non-HTTP 200 status code is also treated as callback failure.
{
"code": "00000",
"message": "success"
}{
"code": "00000",
"msg": "success"
}{
"msg": "success"
}HTTP/1.1 500 Internal Server Error
successOnly return success after signature verification, idempotency checks, and core business processing are complete. If verification or processing fails, do not return success.
Signature Anti-Spoofing Verification
To prevent malicious callback forgery against your callback_url, each callback payload includes sign, a 13-digit timestamp, and a nonce random string.
How to verify authenticity
- Verification runs inside your system. You do not need a new API_SECRET. Use the same project API_KEY used when sending requests.
- Sort callback fields by key in lexicographical order, then concatenate as key1value1key2value2...
- Append the concatenated string after API_KEY.
- Compute MD5 for the final string and convert to lowercase.
- Compare the locally calculated digest with callback sign using strict equality (===). A match means the callback is authentic from Cregis.