Skip to content
Developer
/Webhooks/
/Endpoints

Subscription webhooks (1.0.0)

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

{
  "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.

Download OpenAPI description
subscription_webhooks.json
subscription_webhooks.yaml
Overview
URL

https://www.ratepay.com

Ratepay

info@ratepay.com

Languages
Servers
Ratepay integration platform

https://api-integration.ratepay.com/

Endpoints

Operations

Endpoint to retrieve all owned subscriptions.

Request

Retrieves all subscriptions created and owned by the client identified by the JWT token.

Security
JSON Web Token
Headers
Authorizationstringrequired

For each request, a valid access token must be provided in the Authorization header. See Authentication API for obtaining a valid token.

curl -i -X GET \
  https://api-integration.ratepay.com/webhook/management/v1 \
  -H 'Authorization: Bearer <YOUR_JSON Web Token_HERE>'

Responses

Array of subscriptions

Bodyapplication/jsonArray [
idstring(id)= 20 characters([A-Za-z0-9_-]{20})

ID of the subscription.

Example: "d8znR1k1_0Kw305BsoPT"
urlstring(url)

HTTP URL to execute the webhook call with the POST method.

Example: "https://api.merchant.com/event"
event_typestring

Type of the event to process by calling the API endpoint.

Example: "INVOICE_INVOICE"
secretstring>= 64 characters

Parameter given by the client to sign their payloads. Recommended to be unique for each URL.

Example: "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
]
Response
application/json
[
  {
    "id": "d8znR1k1_0Kw305BsoPT",
    "url": "https://api.merchant.com/event",
    "event_type": "INVOICE_INVOICE",
    "secret": "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
  }
]

Endpoint to create a new subscription.

Request

Creates a new webhook subscription accessible only to the client.

Security
JSON Web Token
Headers
Authorizationstringrequired

For each request, a valid access token must be provided in the Authorization header. See Authentication API for obtaining a valid token.

Bodyapplication/jsonrequired
urlstring(url)required

HTTP URL to execute the webhook call with the POST method.

Example: "https://api.merchant.com/event"
event_typestringrequired

Type of the event to process by calling the API endpoint.

Example: "INVOICE_INVOICE"
secretstring>= 64 charactersrequired

Parameter given by the client to sign their payloads. Recommended to be unique for each URL.

Example: "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
curl -i -X POST \
  https://api-integration.ratepay.com/webhook/management/v1 \
  -H 'Authorization: Bearer <YOUR_JSON Web Token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://api.merchant.com/event",
    "event_type": "INVOICE_INVOICE",
    "secret": "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
  }'

Responses

The subscription was created.

Headers
Locationstring(url)

The URL to retrieve all owned subscriptions.

Bodyapplication/json
idstring(id)= 20 characters([A-Za-z0-9_-]{20})

ID of the subscription.

Example: "d8znR1k1_0Kw305BsoPT"
urlstring(url)

HTTP URL to execute the webhook call with the POST method.

Example: "https://api.merchant.com/event"
event_typestring

Type of the event to process by calling the API endpoint.

Example: "INVOICE_INVOICE"
secretstring>= 64 characters

Parameter given by the client to sign their payloads. Recommended to be unique for each URL.

Example: "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
Response
application/json
{
  "id": "d8znR1k1_0Kw305BsoPT",
  "url": "https://api.merchant.com/event",
  "event_type": "INVOICE_INVOICE",
  "secret": "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
}

Endpoint to update the properties of the subscription.

Request

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.

Security
JSON Web Token
Path
idstring(id)= 20 characters([A-Za-z0-9_-]{20})required

Subscription ID received when creating a subscription.

Example: d8znR1k1_0Kw305BsoPT
Headers
Authorizationstringrequired

For each request, a valid access token must be provided in the Authorization header. See Authentication API for obtaining a valid token.

Bodyapplication/json
urlstring(url)required

HTTP URL to execute the webhook call with the POST method.

Example: "https://api.merchant.com/event"
event_typestringrequired

Type of the event to process by calling the API endpoint.

Example: "INVOICE_INVOICE"
secretstring>= 64 charactersrequired

Parameter given by the client to sign their payloads. Recommended to be unique for each URL.

Example: "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
curl -i -X PUT \
  https://api-integration.ratepay.com/webhook/management/v1/d8znR1k1_0Kw305BsoPT \
  -H 'Authorization: Bearer <YOUR_JSON Web Token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://api.merchant.com/event",
    "event_type": "INVOICE_INVOICE",
    "secret": "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
  }'

Responses

OK. The subscription was updated.

Bodyapplication/json
idstring(id)= 20 characters([A-Za-z0-9_-]{20})

ID of the subscription.

Example: "d8znR1k1_0Kw305BsoPT"
urlstring(url)

HTTP URL to execute the webhook call with the POST method.

Example: "https://api.merchant.com/event"
event_typestring

Type of the event to process by calling the API endpoint.

Example: "INVOICE_INVOICE"
secretstring>= 64 characters

Parameter given by the client to sign their payloads. Recommended to be unique for each URL.

Example: "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
Response
application/json
{
  "id": "d8znR1k1_0Kw305BsoPT",
  "url": "https://api.merchant.com/event",
  "event_type": "INVOICE_INVOICE",
  "secret": "6GHbLH4d1Nx3eIs5CyLHCW4HuFi1qttpNSDawHKHlW7kurTpaddarwEKDWUI59IU"
}

Endpoint to unsubscribe from the subscription.

Request

To resubscribe, you need to create a new subscription.

Security
JSON Web Token
Path
idstring(id)= 20 characters([A-Za-z0-9_-]{20})required

ID of the subscription to be deleted.

Example: d8znR1k1_0Kw305BsoPT
Headers
Authorizationstringrequired

For each request, a valid access token must be provided in the Authorization header. See Authentication API for obtaining a valid token.

curl -i -X DELETE \
  https://api-integration.ratepay.com/webhook/management/v1/d8znR1k1_0Kw305BsoPT \
  -H 'Authorization: Bearer <YOUR_JSON Web Token_HERE>'

Responses

OK. The subscription was successfully deleted.

Response
No content