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

Configuration

Before you begin configuring webhooks, make sure you have an endpoint in your application that is capable of receiving webhook payloads. Once you do, 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

Log in to your Rootline account
Navigate to the Developer section in your account settings, and choose Webhooks
Click on the Create new endpoint button
Fill out the required fields, and select the events and the accounts you want to configure the webhook for
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

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

accepted

If we don't receive your response as instructed in step 1, we will retry sending the webhook with an exponential backoff. The `Retry in t after the first attempt

# 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": "2023-11-15T09:27:51.595642Z",
  "livemode": false,
  "api_version": "2024-04-23",
  "payment": {
    "id": "pmt_4jfu0TAblugHisipqMdmFg",
    "created_at": "2023-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.

Event types

Payment events

event_type	Description
payment.succeeded	Your payment was successfully authorized
payment.failed	The payment failed. The authorization was declined or had an error

Authorization events

event_type	Description
authorization.approved	The authorization attempt was approved
authorization.declined	The authorization attempt was declined
authorization.error	The authorization attempt had an error

Authentication events

event_type	Description
authentication.pending	An authentication attempt is pending. Consequently, the API response will indicate whether or not the authentication attempt was successful

Capture events

event_type	Description
capture.scheduled	A capture was successfully created and scheduled for submission to the network
capture.scheduled.failed	A capture was requested, but failed before sending the request to the schemes
capture.failed	A capture was sent to the network, but in the process it failed

Refund events

event_type	Description
refund.scheduled	A refund was successfully created and scheduled for submission to the network
refund.authorized	A refund request was authorized by the issuing bank
refund.scheduled.failed	A refund was requested, but failed before sending the request to the schemes
refund.failed	A refund was sent to the network, but in the process it failed

Cancel events

event_type	Description
cancel.scheduled	A cancel was successfully created and scheduled for submission to the network
cancel.scheduled.failed	A cancel request was done, but failed before sending the request to the schemes
cancel.failed	A cancel was sent to the network, but in the process it failed
canceled	The cancel request is confirmed with success

Reports

event_type	Description
report.created	A report was successfully created and is ready to be downloaded

Account activation

event_type	Description
company.created	A company was successfully created
person.created	A person was successfully created
account.created	An account was successfully created and is available for payments processing