Webhooks Implementation Guide

Riverty webhooks allow your system to receive real-time notifications whenever important BNPL events occur - such as authorizations, payment status updates, invoice events, or refunds.

Instead of polling our APIs, your backend receives an HTTPS POST request immediately when something changes.

1. Getting started

To receive webhooks, you must:

1. Provide a public HTTPS endpoint
2. Reach out to your implementation manager to request the configuration of the endpoints
3. Store the Shared Secret
4. Validate incoming requests using the Riverty-Signature header
5. Return an HTTP 2xx response if processing succeeds

Only HTTPS endpoints are supported.

2. Webhook Structure

Each webhook message sent by Riverty follows a consistent structure consisting of:

• a Header - metadata describing the event
• a Body - business-relevant content specific to the event type

Below is an example:

{
  "Header": {
    "TransmittedTimestamp": "2024-05-02T11:37:54.7535534+02:00",
    "ClientId": 12523,
    "MessageName": "AuthorizeAccepted",
    "Version": "1.0",
    "MessageId": "9e0a0000-569c-0050-45ab-08dc6a80f6f7",
    "ShopId": "RTY000002240",
    "CountryCode": "DE"
  },
  "Body": {
    "OrderNumber": "6864260723",
    "AdditionalPaymentInfo": "XaWRUzsIs7YMN6oHPqeCItZz4H1XOavo",
    "ParentTransactionReference": "MXTXSAD36PRRVS70"
  }
}

2.1 Header Fields

Field	Description
TransmittedTimestamp	Exact timestamp when Riverty sent the webhook. Used for ordering and replay protection.
ClientId	Merchant account identifier.
MessageName	The event type (e.g., AuthorizeAccepted, InvoiceCreated). Determines the Body structure.
Version	Version of the webhook message format.
MessageId	Unique ID for this webhook. Use this for idempotency.
ShopId	Shop or merchant instance where the transaction originated.
CountryCode	ISO country code related to the event.

2.2 Body Fields

The Body contains the event-specific business data. The Body structure varies by MessageName. Each event type only contains the fields needed for the relevant workflow.

3. Authenticating Webhooks

Every webhook request includes a Riverty-Signature header:

Riverty-Signature: t=1715780015, v1=ada4a220ba1879410b20c553b54b6255930a4486f628aaa630f80a41432d95a7

3.1 Header Components

Field	Description
t	Unix timestamp (seconds) when Riverty generated the webhook.
v1	HMAC-SHA256 signature of the timestamp + raw request body.

3.2 Signature Calculation

Riverty computes the signature as:

signature = HMAC_SHA256(
    key = <shared_secret>,
    message = "{timestamp}{rawBody}"
)

3.3 Validating the Signature

To validate:

1. Read the raw request body (as a string).
2. Parse t= and v1= from the header.
3. Reject requests older than 5 minutes to avoid replay attacks.
4. Recalculate HMAC using your shared secret.
5. Compare using a constant-time comparison.
6. Only process the webhook if the signatures match.

4. Returning Responses

Your endpoint must return:

• 2xx response → Delivery successful
• Non-2xx or timeout → Riverty retries

We recommend responding with 200 OK as soon as the event is accepted for processing.

5. Automatic Retries

If your endpoint is unavailable or returns an error, Riverty will retry delivery for up to 24 hours.

Common retry behaviour:

Attempt	Delay
1	1 minute
2	5 minutes
3	10 minutes
4	increasing exponential backoff
...	up to 24 hours total

Retries stop immediately after a 2xx response.

Events that cannot be delivered after the retry window are marked as failures.

6. Best Practices

✔ Idempotency

Use the MessageId field to ensure each event is processed only once.

✔ Logging

Log:

• MessageId
• Timestamp
• MessageName

Avoid logging sensitive fields.

✔ Security Recommendations

• Use HTTPS endpoints only
• Validate the Riverty signature
• Enforce timestamp freshness
• Reject invalid origins or malformed payloads

✔ Async Processing

Return a 2xx immediately and process the event asynchronously.

7. Testing Webhooks

• Sandbox and Production environments use different secrets.
• You can trigger test transactions to generate webhook events.
• Test replay handling by temporarily returning HTTP 500.