Migration Guide: Yapily Notification API to Webhook API

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 .
• Review the Webhook API Documentation .
• Familiarize with the Webhook Introduction Guide .
• Refer to the Webhook Get Started Guide .

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 .

Java JDK for Webhook Integration

A dedicated Java SDK is available for the Webhook API, offering streamlined integration and enhanced features. For more details on integrating the SDK, refer to the Webhook Java SDK 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.