> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/developers/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction to Webhooks and Callbacks
> Introduction to webhooks and callbacks in WaaS 2.0, explaining their purpose and implementation.
Try [Cobo WaaS Skill](/v2/guides/overview/cobo-waas-skill) in your AI coding assistant (Claude Code, Cursor, etc.). Describe your needs in natural language to auto-generate production-ready SDK code and debug faster 🚀
Webhooks and callbacks are essential mechanisms for the WaaS service to communicate with your application. After you set up and register callback and webhook endpoints, the WaaS service sends push messages to the designated URL when an event occurs. They allow your application to receive real-time updates or notifications and to respond to events accordingly.
## 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`). |
You can view the data of all webhook events and callback messages in your organization on **Cobo Portal** > **Developer**> **Webhook Events** / **Callback Messages**.
## Handle webhook events and callback messages
Follow the steps listed below to handle webhook events and callback messages sent from the WaaS service:
1. Create a webhook or callback endpoint.
* Choose a server environment.
* Define an endpoint URL.
2. 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).
3. Register the endpoint on Cobo Portal.
When registering a webhook endpoint, you need to specify the event types to which you want to subscribe.
To create an endpoint and implement the handling logic, see [Set up a callback or webhook endpoint](/v2/guides/webhooks-callbacks/set-up-endpoint).
To register the endpoint, see [Register a webhook endpoint](https://manuals.cobo.com/en/portal/developer-console/webhooks-create) and [Register a callback endpoint](https://manuals.cobo.com/en/portal/developer-console/callbacks-register).
To learn more about event types and event data types, see [Webhook event type and data type](/v2/guides/webhooks-callbacks/webhook-event-type).
To manage webhook events using Cobo CLI, refer to the following guides: [Listen and Forward Events](/v2/developer-tools/cobo-cli/listen-and-forward-events), [Trigger Webhook Events](/v2/developer-tools/cobo-cli/trigger-events), and [List Event Types](/v2/developer-tools/cobo-cli/event-types).
## 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 |
For more details about the WaaS 1.0 callbacks, refer to [How to Configure API Callback](/v1/guides/howtos/configure-api-callback).
### 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](/v2/guides/webhooks-callbacks/set-up-endpoint).
* Register the endpoint on the Cobo Portal by following the instructions in [Register a webhook endpoint](https://manuals.cobo.com/en/portal/developer-console/webhooks-create) or [Register a callback endpoint](https://manuals.cobo.com/en/portal/developer-console/callbacks-register).
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](/v2/guides/webhooks-callbacks/set-up-endpoint#code-samples) 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.
In this case, you need to implement deduplication using a unique ID (such as `cobo_id`) to avoid processing duplicate notifications.