Webhooks

A webhook enables Lender & Spender to push real-time notifications to your application. Lender & Spender uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Getting started

1. Identify the events you want to monitor and the event payloads to parse.

2. Create a webhook endpoint as an HTTPS endpoint (URL) that handles requests from Lender & Spender by parsing each event object and returning a 2xx response status code.

3. Register your publicly accessible HTTPS URL in your intermediary dashboard. 

Webhook events

Each event is structured as an event object with a type and related resource under data. Your endpoint must check the event type and parse the payload of each event.

Loan application status update

Occurs when the status of a loan application is updated.
data contains a LoanApplication object

{
  "type": "loan_application_status_update",
  "data": {...}
} 

Loan application attention required

Occurs when attention is required to the loan application. More information is provided in message. Make sure to reload the list of required documents on the LoanApplication object, as they could have been updated as wel.
data contains a LoanApplication object

{
  "type": "loan_application_attention_required",
  "message": "Message containing specific information.",
  "data": {...}
} 

Webhook test

Can be triggered from the intermediary dashboard, to test response of the registered webhook URL.

{
  "type": "webhook_test",
  "data": {
      "status": "success"
  }
} 

Authentication

All webhooks we send will be signed by a signing secret, with can be set in your dashboard. You don't have to validate the incoming request, but it's highly suggested.

Webhook authentication & signing

Our signing method is simple but efficient. For every webhook we call, we pass an additional header called Signature that contains the hash of the payload.

In your webhook, you can validate if that Signature header contains the hash you expected.

It's calculated as follows:

$computedSignature = hash_hmac('sha256', $payload, $secret);

The $payload is the body of the POST request, which will be a JSON representation of event.

The $secret can be found in your dashboard.

The hash_hmac() function is a PHP function that generates a keyed hash value using the HMAC method.

The $computedSignature should match the Signature that's been set.

Retrying failed webhooks

When your application fails to send a response with a 2xx status code (within 3 seconds) the webhook call will be considered as failed.

When a webhook call fails, we'll retry automatically with the following exponential backoff strategy: we wait 10 seconds between the first and second attempt, 100 seconds between the third and the fourth, 1000 between the fourth and the fifth and so on. The maximum amount of seconds that we'll wait is 100.000, which is about 27 hours.