Introduction to Notifications

Webhooks are a way for YouLend to notify partners when a significant event for a lead or an agreement has taken place.

For setup and delivery guidance, see the Webhook guide.

Recommended event codes

Review the recommended event codes to implement first.

Create a webhook subscription

Host an endpoint and subscribe it to the event codes you need.

Process notification payloads

Inspect the notification format and return a timely 2xx response.

Verify webhook requests

Use your subscription secret key to verify that requests come from YouLend.

Partners need to host a webhook endpoint and then provide YouLend with the URL by creating a webhook subscription via API.

Example request

curl -X POST 'https://partners.staging-youlendapi.com/notification/webhooksubscription' \
      -H 'authorization: Bearer ACCESS_TOKEN' \
      -H 'Content-Type: application/json' \
      -d '{
           "eventCodes": ["ONB10001","ONB10002","ONB10003","ONB10004","LOA10013"],
           "webhookUrl": "https://your_url.com"
          }'

Partners subscribe to specific event types, and when an event of that type occurs, YouLend sends a POST request to the partner-provided URL. See Webhook events for the available event codes and their meanings.

Example response

{
    "EventCode": "ONB10011",
    "Message": "Offers Provided",
    "EventProperties": {
        "LeadId": "f3c23809-9850-4546-bd08-650068aa55f6",
          "Offers": [
              {
                "OfferId": "d08292ef-b034-4b64-a4c6-ad2babd46dbd",
                "YouWillGet": "1000.0",
                "YouWillRepay": "1200.0",
                "CurrencyISOCode": "GBP",
                "Sweep": "20.0"
              }
           ]
     }
}

Webhooks can be used to notify event changes throughout the application process, from applications being created through to signed, and agreements being funded through to fully repaid. For help triggering events in our staging environment, please get in touch with your account or implementation manager.

It is important your server returns a 2xx status code in a timely manner so we know you have successfully received the notification. Our server will retry the attempt in 15 second intervals (3 times) if we don't receive a 2xx response.

📘
Good to know
You can create multiple subscriptions if you do not want to use the same endpoint for every event. Events are sent to the endpoint configured for the corresponding subscription.

Webhook Map

The highlighted options are the recommended event codes to implement first