riverty logo

Docs

Get Started Login

Webhooks

Webhooks allow your application to receive notifications when specific events occur. By setting up webhooks, you can automate workflows and respond to events as they happen. This guide will walk you through the steps to integrate webhooks into your system.

Integration Steps:

To process webhook events, follow these steps:

  1. Set up your endpoint
  2. Set up your webhook configuration
  3. Accept webhook events

Step 1: Set up your endpoint

To receive webhook events, you need to create an endpoint on your server that can handle POST requests. Your webhook endpoint must be a publicly accessible HTTPS URL.

Here are some key considerations when setting up your endpoint:

  • Return a 2xx status code quickly before performing any complex logic to prevent timeouts.
  • Implement security best practices, such as verifying webhook signatures and validating incoming requests. (For more details, check Step 3.)

Step 2: Set up your webhook configuration:

To start using webhooks, you need to provide the following details to our integration team:

  • Endpoint URL: The HTTPS URL you created in Step 1, where webhook events will be delivered. We recommend using separate URLs for testing and live environments.

  • Events: Specify which events you want to receive.

Once submitted, our integration team will register your endpoint with our webhook service.

Step 3: Accept webhook events

Riverty sends all events with a custom signature, which uniquely encodes each payload body. To verify the messages received at your webhook endpoint, you need to decode the payload body using our shared secret.

Retrieve and store secret

Upon registering a configuration for your webhook endpoint, we will generate a unique shared secret that our integration will share with you. This secret should be stored safely, preferably in a key vault or similar. To validate all events sent by Riverty, you need to retrieve this secret from your storage in order to decode the custom Riverty-Signature from the request header.

Riverty-Signature:
t=1715780015,
v1=ada4a220ba1879410b20c553b54b6255930a4486f628aaa630f80a41432d95a7
  • Riverty-Signature = Custom signature for Riverty
  • t = timestamp
  • v1 = signature

Validating header signature

Here is a high level overview of how you can receive and validate events:

1.Receive the webhook payload

Receive the POST request.

2.Extract necessary information

Extract the Riverty-Signature from the request header and the message from the request body

3.Extract the timestamp and signature from the header

The Riverty-Signature header of the webhook request contains the timestamp and signature, separated by a comma.

The timestamp is prefixed with t= and the signature is prefixed with v1=.

Split the header on the comma to get the two parts, then split each part on the = to get the timestamp and signature.

headerSignature = "<Riverty-Signature header from the webhook request>"
parts = split headerSignature by ','
timestampPart = find and split the part that starts with "t=" by '=' and take the second element
signaturePart = find and split the part that starts with "v1=" by '=' and take the second element

4.Check the timestamp(optional)

The timestamp from the signature key in the request header is the time the webhook request was sent, in seconds since the Unix epoch. Compare this to the current UTC UNIX time to ensure the request is not a replay attack. If the difference is more than 5 minutes, the request should be rejected.

headerTimestamp = convert timestampPart to a number
currentTimestamp = get current UTC Unix timestamp
timeDifference = absolute difference between currentTimestamp and headerTimestamp
if timeDifference > 5 * 60 then throw an exception

5.Retrieve the shared secret

Obtain the shared secret from your storage to validate the header.

6.Validate the signature

The signature is a HMAC SHA256 hash of the timestamp and the message body, using the secret key.

To validate the signature, compute the hash of the timestamp and the received message body using the same secret key, and compare it to the received signature.

Confirm the signature's validity using the timestamp, signature string, payload, and shared secret (return status code 401 Unauthorized if the header is invalid)

receivedMessage = "<raw json string from the HttpContext.Request.Body>"
secretKey = "<your secret key>"
messageWithTimestamp = headerTimestamp + receivedMessage

keyByte = convert secretKey to byte array
messageBytes = convert messageWithTimestamp to byte array

computedHash = compute HMACSHA256 hash of messageBytes using keyByte
computedSignature = convert computedHash to hexadecimal string, remove '-' characters and convert to lowercase

if computedSignature != signaturePart then throw an exception
if computedSignature == signaturePart then the message is considered valid

7.Quickly return a response

Once the signature is validated and the message has been parsed, your endpoint must promptly return a 2xx status code** before executing any complex logic that might cause a timeout.** For instance, it should return a 200 response before updating a customer's invoice as paid in your accounting system

Do you find this page helpful?