# Webhooks

## Overview

**Webhooks** allow you to receive real-time notifications about events that happen in your Ryft account. This enables you to automate workflows and keep your systems in sync with Ryft.

Please note we currently allow only **one webhook endpoint per account**. If you need additional endpoints, please reach out to our support team.

## Webhook API

Ryft provides a [Webhook API](/documentation/api/reference/openapi#operation/Webhooks) that allows you to manage your webhook endpoints. You can create, update, retrieve, and delete webhook endpoints.

We highly recommend to use webhooks to stay informed about important events in your Ryft account. This ensures that your systems are always up-to-date and can respond to events in a timely manner.

## Viewing Webhooks via the Portal

You can view and manage your webhook endpoints directly from the **Ryft Portal**. Click on your profile icon in the top right corner, then select **Developer** from the dropdown menu. Next, navigate to the **Webhooks** section in the sidebar. From here, you can create new endpoints, edit existing ones, or delete those that are no longer needed.

The **Events** section allows you to see a list of all events that have been sent to your webhook endpoints. This is useful for monitoring and debugging purposes.

## Webhook Authorization

To **verify** that incoming webhook requests are from Ryft, you can use the `Signature` header included in each request. This header contains a signature that you can validate using your webhook secret.

You can achieve this as follows:

1. `HMAC-SHA256` hash the raw response body.
2. Compare the resulting hash to the value in the `Signature` header.
3. If they match, the request is valid. If they don't, you should reject the request.


## Retry Policy

Systems responding to webhook events should be lightweight and offload any required processing asynchronously. This allows you to manage any necessary **retries** for failures that occur during processing. Doing so ensures that your system can handle transient issues without losing important event data.

Despite your best efforts, there may be times when your system is unavailable or unable to process webhook events. In such cases, Ryft have implemented a retry policy to ensure that you still receive the events.

As soon as your webhook URL becomes unreachable, Ryft will begin retrying the delivery of events which occurs at increasing intervals. This exponential backoff strategy helps to avoid overwhelming your system with repeated requests.

**Each retry occurs after 0, 1, 5, 10, 10 minutes and a third 10 minute delay.**

For instance, if a webhook event is sent at 15:00 and your server is down, the retry schedule would look like this:

| Attempt | Attempted After | Attempted Time |
|  --- | --- | --- |
| 1 | 0 minutes | 15:00 |
| 2 | 1 minutes | 15:01 |
| 3 | 5 minutes | 15:06 |
| 4 | 10 minutes | 15:16 |
| 5 | 10 minutes | 15:26 |
| 6 | 10 minutes | 15:36 |


We expect a `200` response status code within **1.5 seconds** of sending the webhook event. If we do not receive a `200` status code within this timeframe, we will consider the delivery attempt to have failed and will schedule a retry according to our retry policy.

## Webhook Categories

We have divided our webhooks into three different **categories** based on the type of events they relate to. The main categories are:

- **Sub-Accounts**: Events related to the lifecycle of sub-accounts, such as creation, updates, and verification status changes, but also Payout Methods and Payout management.
- **Payments**: Events related to payment processing, including payment initiation, success, failure, refunds and disputes.
- **Subscriptions**: Events related to subscription management.


Sub-Account Webhooks
Learn about the various webhook events related to Sub-Accounts, including creation, updates, and verification status changes.

Payments Webhooks
Discover the webhook events associated with payment processing, such as payment initiation, success, failure, refunds, and disputes.

Subscriptions Webhooks
Explore the webhook events related to subscription management.