Webhooks vs callbacks
Callbacks and webhooks serve distinct purposes within your business operations.| Mechanism | Description | Trigger Condition | Required Actions Upon Receiving the Message |
|---|---|---|---|
| Callbacks | Serve similarly to a 2FA verification. You must register a callback endpoint in order to approve and complete a token withdrawal. | Triggered when you initiate a withdrawal or contract call using the WaaS API. | Check if the transaction meets expectations, and respond with a success status code (200 or 201) and a response body of ok or deny to indicate transaction approval or rejection. |
| Webhooks | Serve as real-time notifications for events such as transaction status updates. | Triggered when certain events occur such as transaction status or TSS request status changes, based on the event types to which you subscribe. | Respond with a success status code (200 or 201). |
Handle webhook events and callback messages
Follow the steps listed below to handle webhook events and callback messages sent from the WaaS service:- Create a webhook or callback endpoint.
- Choose a server environment.
- Define an endpoint URL.
- Implement the handling logic on the server side.
- Parse the API request.
- Verify the signature.
- Respond to the API request.
- Add other handling logic (if applicable).
- Register the endpoint on Cobo Portal.
When registering a webhook endpoint, you need to specify the event types to which you want to subscribe.
Notes on upgrading from WaaS 1.0 to Waas 2.0
The WaaS 1.0 service uses API callbacks for transaction notifications and withdrawal confirmations, similar to the webhooks and callbacks introduced in WaaS 2.0. The following table provides a comparison between the two versions based on the event notification mechanisms:| Mechanism to Notify Transaction Status Changes | Mechanism to Confirm Withdrawals | Where to Register the Endpoint | |
|---|---|---|---|
| WaaS 1.0 | Callbacks - Transaction notifications | Callbacks - Withdrawal confirmations | Cobo Custody |
| WaaS 2.0 | Webhook events | Callback messages | Cobo Portal |
Continued use of the WaaS 1.0 API
If you choose to continue using the WaaS 1.0 API, no additional configuration is required. The existing API callbacks will function as expected.Upgrade to the WaaS 2.0 API
When upgrading to WaaS 2.0, you need to do the following:- Set up your webhook or callback endpoint by following the instructions in Set up a callback or webhook endpoint.
- Register the endpoint on the Cobo Portal by following the instructions in Register a webhook endpoint or Register a callback endpoint.
The WaaS 1.0 API callbacks use a different signature algorithm compared to the WaaS 2.0 webhooks and callbacks. Do not directly register your WaaS 1.0 endpoint on Cobo Portal. Otherwise, your endpoint will receive errors due to the differences in the signature algorithm and webhook/callback data structure between WaaS 1.0 and WaaS 2.0. Ensure you refer to the sample code provided to correctly configure your endpoint for WaaS 2.0.
If you configure WaaS 1.0 API callbacks for transaction notifications but do not set up WaaS 2.0 webhooks, your endpoint will still receive transaction notifications from WaaS 1.0.
If you configure both WaaS 1.0 API callbacks for transaction notifications and WaaS 2.0 webhooks, while continuing to use the WaaS 1.0 API, your endpoint will receive:- From WaaS 1.0: Transaction notifications.
- From WaaS 2.0: Webhook events.
cobo_id) to avoid processing duplicate notifications.Feel free to share your feedback to improve our documentation!