---
updatedAt: 2026-08-27T12:36:17.000Z
agentTools:
  projectIndex: https://docs.youlend.com/llms.txt
---

# Webhooks

Create webhook subscriptions and receive YouLend event notifications.

Use webhooks to receive YouLend event notifications when a lead or agreement changes state.

A webhook is an HTTPS endpoint that you host. After you create a webhook subscription through the YouLend Notification API, YouLend sends a `POST` request to your endpoint whenever a subscribed event occurs.

<Cards>
  <Card title="1. Host an endpoint" href="#creating-a-webhook" icon="fa-server">
    Create an endpoint that can receive YouLend webhook notifications.
  </Card>

  <Card title="2. Subscribe to events" href="#creating-a-webhook" icon="fa-bell">
    Send YouLend your endpoint URL and the event codes you want to receive.
  </Card>

  <Card title="3. Process notifications" href="#example-notification-payload" icon="fa-code">
    Return a timely `2xx` response after your endpoint receives each notification.
  </Card>
</Cards>

Webhooks can notify you about changes throughout the application process, from applications being created and signed to agreements being funded and fully repaid. For help triggering events in the staging environment, contact your account or implementation manager.

<Callout icon="📘" theme="info">
  ### Good to know

  You can create multiple webhook 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.
</Callout>

## Recommended event codes

<Image src="https://files.readme.io/85a7291fe45b6bbdf7c1e5eb0798555f947a3a756ea5ef130cb20e3349c661d2-image.png" align="center" caption="White boxes are normal progress updates. Blue boxes are the main milestones, like offers provided, contract signed, and funded. Yellow boxes mean something needs attention, or the offer has expired. Red boxes show rejected or risk states. Green boxes show recovery or completion, like out of collections or repaid." />

## Creating a webhook

Create a subscription through the YouLend Notification API to connect your endpoint to specific event codes.

1. Host an HTTPS endpoint that can receive `POST` requests.
2. Choose the event codes you want to subscribe to.
3. Send your endpoint URL and event-code list to the webhook subscription endpoint.

Whenever one of the subscribed events occurs, YouLend sends a webhook notification to your endpoint.

### Example request to [create a subscription](https://docs.youlend.com/reference/post_webhooksubscription)

```curl
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"
          }'
```

| Environment      | URL                                                                          |
| :--------------- | :--------------------------------------------------------------------------- |
| EU (staging)     | `https://partners.staging-youlendapi.com/notification/webhooksubscription`   |
| EU (production)  | `https://youlendapi.com/notification/webhooksubscription`                    |
| USA (staging)    | `https://uspartners.staging-youlendapi.com/notification/webhooksubscription` |
| USA (production) | `https://youlendapi.us/notification/webhooksubscription`                     |

After you create the subscription, YouLend sends a notification to the provided URL when any subscribed event occurs. For help triggering events in the test environment, contact your account manager.

## Example notification payload

YouLend sends notifications to your endpoint as JSON payloads. The example below shows an `ONB10011` event for an offer being provided.

```json
{
    "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"
              }
           ]
     }
}
```

<Callout icon="⚠️" theme="warn">
  ### Important

  Your endpoint must return a `2xx` status code in a timely manner so YouLend knows the notification was received. If YouLend does not receive a `2xx` response within 100 seconds, YouLend retries the request 2 more times over a period of 2 minutes.
</Callout>

## Verify webhook requests

The create subscription response includes a secret key that is unique to each subscription. Use this secret key to verify that webhook requests are coming from YouLend. For verification details, see [Webhooks verification](https://docs.youlend.com/reference/webhooks-verification).