> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Guide Notification API to Webhook API

> This guide provides a comprehensive walkthrough of the necessary steps to seamlessly migrate from the deprecated Notification API to the enhanced Webhook API.

<Note>
  Webhooks is available as a [Private Beta version](/getting-started/overview#private-beta).
  Please contact your Customer Success Manager if you would like to access it.
</Note>

## Introduction

This guide provides instructions on how to migrate from the deprecated **Notification API** to the enhanced **Webhook API**. The Webhook API offers improvements, such as the ability to subscribe to multiple event categories within a single webhook. The steps outlined here facilitate a smooth migration process.

***

## Prerequisites

Before proceeding with the migration, it is necessary to:

* Obtain a Yapily Access Token.
* Review the [Notification API Documentation](/api-reference/notifications).
* Review the [Webhook API Documentation](/api-reference/webhooks).
* Familiarize with the [Webhook Introduction Guide](/tools-and-services/webhooks/introduction).
* Refer to the [Webhook Get Started Guide](/tools-and-services/webhooks/get-started).

***

## Steps to Migrate

### 1. Remove Existing Subscriptions from Notification API

The Notification API allows only one subscription per event type. To migrate to the Webhook API, any existing subscriptions must be removed first.

* **Retrieve existing subscriptions:** Call the following endpoint: `GET /notifications/event-subscriptions`. Locate the `eventTypeId` in the response under `response.data[].eventTypeId`.

* **Remove subscriptions:** For each `eventTypeId`, call: `DELETE /notifications/event-subscriptions/{eventTypeId}`.

#### 1.1 Remove a Sub-Application Subscription

Follow the instructions outlined in [step 1](/tools-and-services/webhooks/webhook-migration#1-remove-existing-subscriptions-from-notification-api) and add the following changes to the request:

* for all the http request set a request header `sub-application` with the value being sub-application id

### 2. Retrieve Event Categories from Webhook API

Once the existing subscriptions are removed, begin setting up webhook subscriptions in the Webhook API.

* **Retrieve available event categories:** Use the following endpoint to see all available event categories: `GET /webhook/events/categories`. The Webhook API allows multiple event categories to be subscribed to within a single webhook, unlike the Notification API.

### 3. Register for New Webhook Subscriptions

After identifying the desired event categories, follow the steps to register the webhook.

* **Register the webhook:** Call the following endpoint: `POST /webhook/events`. This API call allows the registration of multiple event categories in a single request.

#### 3.1 Webhook Sub-Application Migration

Follow the instructions outlined in [step 3](/tools-and-services/webhooks/webhook-migration#3-register-for-new-webhook-subscriptions) and add the following changes to the request:

* add a request header `sub-application` with the value being the **sub-application id**
* in the request body set the `applicationId` field with the same **sub-application id** that was set in the headers

A detailed explanation of registration steps can be found in the [Webhook Registration](/tools-and-services/webhooks/get-started#webhook-registration) page.

***

## Signature Validation Changes

For integrations that validate event signatures using the Notification API, note that the signature process has been updated with the Webhook API.

* After the webhook registration call, a `webhookSecret` will be provided in the response body.
  * **Important:** Record the `webhookSecret` immediately, as it will only be displayed once.
  * This secret is required for validating incoming events. Detailed steps on how to perform validation can be found in the [Webhook Documentation](/tools-and-services/webhooks/get-started#webhook-registration).

***

## Conclusion

The steps provided in this guide facilitate a seamless migration from Yapily's Notification API to the Webhook API. The Webhook API offers greater flexibility with event subscriptions and improved signature validation. Refer to the documentation links for additional guidance and examples.