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. You may add up to 10 different webhook endpoints.
Getting started
Identify the events you want to monitor and the event payloads to parse.
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.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.