> For the complete documentation index, see [llms.txt](https://yokifinance.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yokifinance.gitbook.io/docs/subscription-payments/for-merchant/api-integration/introduction.md).

# Introduction

This page describes high-level how a merchant can get [notifications about subscription statuses](/docs/subscription-payments/for-merchant/get-subscription-statuses.md) via API. To read more about API and its objects please go to [API brief overview](/docs/subscription-payments/for-merchant/api-integration/api-brief-overview.md).

Yoki notifies the merchant by firing webhook handler URL (provided by merchant) with POST request upon the following events:

1. [Subscription is created](https://api-rps.yoki.fi/swagger#/Sandbox/CallbackSandboxController_subscriptionCreatedExample).
2. [Periodic payment is processed](https://api-rps.yoki.fi/swagger#/Sandbox/CallbackSandboxController_paymentProcessedExample).
3. [Periodic payment is failed](https://api-rps.yoki.fi/swagger#/Sandbox/CallbackSandboxController_paymentFailedExample). We provide a retry mechanism, so there can be two cases:

   1. Subscription went to error state (e.g., not enough funds or allowance) and stopped.
   2. Subscription will try to charge the user in 24 hours (max 5 tries).

   If in the webhook payload *paymentFailedInfo.nextRunDate* is null, then it means it was the last retry and subscription will be stopped.
4. [Subscription is cancelled](https://api-rps.yoki.fi/swagger#/Sandbox/CallbackSandboxController_subscriptionCancelledExample) by the user. This event is fired only when **user intentionally** canceled a subscription.

To see the data that will be passed to your API, you can click to links above and use services like <https://webhook.site/> , <https://webhook-test.com/> (no endorsement), to see the data that comes in.

**Important**: in your actual implementation webhook API must return either an empty response or {} (empty JSON object) and 2XX status code, otherwise call is considered unsuccessful and will be retried. Max number of retries is 18 over the course of 12 hours.