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.

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.

---