Skip to main content
Webhooks is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.

​
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:

​
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 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 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 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.

​
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.