# Subscription webhooks

This is the documentation for the Ratepay webhook subscription API. This API allows to manage webhook subscriptions by creating new subscriptions,
getting a list of all active subscriptions, updating specific subscriptions or cancelling active subscriptions.

# Payload properties

The subscription consists of an event type that triggers the call of a URL, and a secret that is applied to the payload.
There is an N:M association between the event type and the URL. A subscriber can create multiple event types for one URL and
it is possible to subscribe to the same event type with different URLs.

## ID

Every subscription is identified with a [nanoid](https://github.com/ai/nanoid). The ID is required for updating and deleting a subscription.

## URL

The URL is the API resource endpoint the payload is sent to.
The endpoint **must** be able to process **HTTP POST** requests with payload inside the body, no other HTTP method will be called.
As the API does not inform about an incorrect URL, the correctness should be validated by the client.
For example:
* https://dev_api.important-merchant.com/customers/invoices
* https://api-m.sandbox.baseurl.com/v2/customer/orders

## Event Type

Each event type is bound to **one** URL. If it is necessary to respond to different event types with the same URL,
a new subscription is required for each event type.
The API sends messages to each URL configured for a given event type.

## Secret

The secret enables us to validate Ratepay as the originator of a received payload. The secret **must** be at least **64** characters long.
It is recommended to use one secret per URL to avoid a man-in-the-middle attack, but this is not required.
The webhook service signs the payload using the provided secret with the SHA-512 cryptographic hash function.
The hash is calculated on a string representation of the payload. I.e. if the payload is
```javascript
{
  "key": "value"
}
```
then the input for the hash calculation is `'{"key":"value"}'`. The resulting signature for this example with the secret `abc123` would be `4c131d60caea39b5f65625b80270e5305d5a00ebc5d15a00ecf82da9de2fcc8ff45df068a11f8b336890b161eb1fdefafe452d2e452623b37e4bd3277bb348fd`.
The 512-bit signature is inserted in the header named **x-signature**.

# Retries

If a webhook call to a configured URL fails, this API will try to repeat the identical call at a later time.
This process is repeated multiple times with increasing intervals between retries.
When the maximum number of retries is reached, an alarm is raised and a Ratepay employee is notified.
No further attempts are made to reach the URL until the error is resolved.
A webhook call is failed if it either times out or if the response code `x` is not in the range `200<=x<300`.


Version: 1.0.0

## Servers

Ratepay integration platform
```
https://api-integration.ratepay.com
```

## Security

### JSON Web Token

The authorization of an API user is validated through a JSON Web Token (JWT). The token should be located in the header as:

* `Authorization: Bearer <jwttoken>`

The process to request a token is described in the [ratepay authentication documentation.](/docs/developer/authentication/authentication/)


Type: http
Scheme: bearer
Bearer Format: JSON Web Token

## Download OpenAPI description

[Subscription webhooks](https://docs.ratepay.com/_bundle/apis/webhooks/subscription/openapi/subscription_webhooks.yaml)

## Endpoints

### Endpoint to retrieve all owned subscriptions.

 - [GET /webhook/management/v1](https://docs.ratepay.com/apis/webhooks/subscription/openapi/subscription_webhooks/endpoints/getsubscriptions.md): Retrieves all subscriptions created and owned by the client identified by the JWT token.

### Endpoint to create a new subscription.

 - [POST /webhook/management/v1](https://docs.ratepay.com/apis/webhooks/subscription/openapi/subscription_webhooks/endpoints/createsubscription.md): Creates a new webhook subscription accessible only to the client.

### Endpoint to update the properties of the subscription.

 - [PUT /webhook/management/v1/{id}](https://docs.ratepay.com/apis/webhooks/subscription/openapi/subscription_webhooks/endpoints/updatesubscription.md): # Update Subscription
---

The request body must contain the complete information about the subscription.

The following values can be updated: The __URL__ used for the webhook, the __event type__ applied to this URL and the __secret__, which is used to sign the payload.
It is not possible to change the identification of the subscription.

Omitting properties from the request body (e.g. secret) will result in a validation error and return the status code 400.

### Endpoint to unsubscribe from the subscription.

 - [DELETE /webhook/management/v1/{id}](https://docs.ratepay.com/apis/webhooks/subscription/openapi/subscription_webhooks/endpoints/deletesubscription.md): To resubscribe, you need to create a new subscription.