Configure webhooks

This page provides step-by-step instructions to configure an endpoint to receive Rootline webhooks. Webhooks will help you stay informed and updated about events that happen on the Rootline platform. We recommend using HMAC signatures for securing the webhooks you receive.

Accepting and processing webhook events

At busy times, many webhook events could be sent to you in short periods of time. To optimize for performance it is important to respond to Rootline's POST requests fast without applying complex logic first. The process of listening to webhook events should be decoupled:

1. Respond to Rootline's POST request by sending back accepted as soon as you stored the request;
2. Separately process the webhook for any business logic that you want to apply.

Furthermore, we advise to use separate webhook endpoints for:

1. Events that require fast turnaround with customers;
2. Events that are less time sensitive, such as events for asynchronous capture and refund requests.

For instance, payment.succeeded or any other payment.[event] should be coming in on a designated endpoint, while capture or refund events go to another consumer. When implemented well, you can continue receiving urgent payment events, even when your consumer for less time sensitive events is down.

info

Though Rootline intends to send the events in the order that they were created, we do not guarantee the order in which events are sent.

Handling duplicate events

There can be occasions where you might receive webhook events more than once. Your system should be albe to handle these duplicate events.

You can identify duplicate events by checking both the event_type & id of the object (e.g. "payment").

Configuration

Make sure you have an endpoint in your application that is capable of receiving webhook payloads. Once you have that, follow the below steps to setup your webhook connection.

1. Configure your webhook endpoint through the dashboard
2. Copy your HMAC secret key
3. Acknowledge that you received our webhook
4. Verify the webhook's signature with your HMAC secret key

1: Configuring your webhook endpoint

1. Log in to your Rootline account
2. Navigate to the Developer section in your account settings, and choose Webhooks
3. Click on the Create new endpoint button
4. Fill out the required fields, and select the events and the accounts you want to configure the webhook for
5. Submit the configuration

2: Copy your HMAC secret key

Now that you have you created your webhook configuration, review it, and copy the HMAC secret key, that you will use to compute the HMAC signature.

Keep the secret key secure and do not share it with unauthorized individuals. You won't be able to restore the key later.

3: Acknowledge that you received our webhook

1. To acknowledge receiving our webhook, respond with a 200 http code, along with the below body:

accepted

2. If we don't receive your response as instructed in step 1, we will retry sending the webhook with an exponential backoff.

# retry	Retry time (time after the first attempt)
1	5 seconds
2	20 seconds
3	5 minutes
4	60 minutes
5	12 hours
6	24 hours

4: Verify the webhook's signature with your HMAC secret key

To verify that the webhook and its content has not been tampered with, compute the HMAC signature and compare it with the signature sent in the rootline-signature header. The signature that you computed should match the signature provided by Rootline.

Compute the HMAC signature, and use the HMAC secret key from step 3 and the raw body of the payload. The algorithm you use is HMAC-SHA256.

Example of a webhook event

Rootline sends webhooks for many different events and objects. With every event, you'll receive an event_type, which tells you for which event Rootline sent you the webhook. Furthermore, you're sent the object id, the same id that was returned to you when the object was created. Here's an example of an event for a payment:

{
  "object": "event",
  "webhook_endpoint_id": "webh_jZxJttOF0Mt8EoPGIsebk",
  "event_type": "payment.succeeded",
  "event_time": "2024-11-15T09:27:51.595642Z",
  "livemode": false,
  "api_version": "2024-04-23",
  "payment": {
    "id": "pmt_4jfu0TAblugHisipqMdmFg",
    "created_at": "2024-11-13T13:54:45.636703Z",
    "account_id": "acc_12347Sifdo36cdycbsw4Pum",
    "reference": "ideal payment",
    "amount": {
      "currency": "EUR",
      "quantity": "20.00"
    },
    "checkout_status": "succeeded",
    "return_url": "https://your-url.com/"
  }
}

In addition to your usual response headers, the following our returned as well:

rootline-version: which contains the API version that you configured for this webhook. We advise for this to be in line with the Rootline API version that you're using.

rootline-signature: the signature that should match with the signature using the HMAC secret and the payload that is sent, as described in step 3.