Webhooks

A webhook is an HTTP request that LendAPI sends to your server when something happens to an application, for example when it is approved or booked. Webhooks let your systems react right away, without polling the API. You register one HTTPS URL per scope (all products, or specific products). LendAPI then sends a JSON POST to that URL for each application event and includes a key you choose so your server can confirm the request came from LendAPI.

Key concepts

• Webhook URL: the HTTPS endpoint on your server that receives events.
• Webhook key: a secret you choose (at least 16 characters, no spaces). LendAPI sends it in a request header with every event.
• Key Name: how the key is sent: Bearer (in the Authorization header) or X-API-Key (in the X-API-KEY header).
• Products: which products the webhook covers. All Products, or one or more specific products.
• Webhook Variables: extra variables you choose to include in every event payload.
• Event: one notification, identified by a unique event_id and an event type such as application.approved.

How it works

sequenceDiagram
    participant L as LendAPI
    participant S as Your server
    Note over L: Application event occurs<br/>(e.g. approved)
    L->>S: POST webhook URL (JSON event + your key)
    alt 2xx within 15 seconds
        S-->>L: 200 OK
    else Error, non-2xx or timeout
        S-->>L: 500 / no response
        Note over L: Wait about 60 seconds, then retry<br/>(up to 3 retries, same event_id)
        L->>S: POST same event again
    end

1. An application event happens, such as a decision or a document upload.
2. LendAPI picks the webhook for that application. A webhook set up for the application's product is used first. If there isn't one, the All Products webhook is used.
3. LendAPI sends the event in the background, so it never slows down the applicant.
4. Your server responds. Any 2xx status within 15 seconds counts as delivered.

Retries

If your server returns a non-2xx status, doesn't respond within 15 seconds, or can't be reached, LendAPI retries the event up to 3 more times, about 60 seconds apart. Every retry carries the same event_id, so you can safely ignore duplicates. After the last failed attempt, the event is not sent again.

Environments

Sandbox and Production have separate webhook settings. Events for Sandbox applications are sent to the webhook configured in Sandbox. See Sandbox and Live.

Event reference

Event types

Expand the list below to see every event type. Your server should accept any event type and ignore the ones it doesn't need. New event types may be added over time.

Payload

Every event is a JSON POST.

{
  "api_version": "v1",
  "event_id": "7f6b2a4e-3c1d-4e8f-9a2b-0c4d5e6f7a8b",
  "type": "application.approved",
  "product_id": 101,
  "outcome": "Auto Approve",
  "data": {
    "app_id": "d130f351-26a1-4698-9b64-92ae8c46c644",
    "tenant_id": "8199c002-0c26-46ec-8aaf-db487f39de1b",
    "current_step_label": "approved",
    "stage": 1,
    "stage_label": "Approved",
    "additional_data": {
      "utm_source": "partner-site"
    },
    "custom": {
      "variables": {
        "annual_income": 85000,
        "requested_amount": 15000
      }
    }
  }
}

Some events add extra top-level fields with event-specific details. For example, application.autowithdrawn includes status_type and inactive_days, and manual_credit_pull includes pull_status, pull_message and bureau_name.

📘

Payload is a notification, not a full record

The payload tells you what happened and to which application. Call the API with data.app_id when you need the full application data.

Set up webhooks

Add a webhook

1. Switch to the environment (Sandbox or Production) you want to configure.
2. Open the profile menu in the top-right corner and select Settings.
3. Open the Webhook tab.
4. Click Webhook (the button with the plus icon).
5. Under Products, keep All Products or choose specific products.
6. Enter the URL. It must use HTTPS.
7. Choose the Key Name: Bearer or X-API-Key.
8. Enter a Webhook Key of at least 16 characters with no spaces.
9. Click Add Webhook.

The new webhook is active right away. To add variables to the payload, click Add Variables in the webhook's Variables column and choose them in the Webhook Variables dialog.

From the webhook list you can also view or copy the key, edit the webhook, and turn it on or off with the Status switch.

🚧

One active webhook per scope

Only one webhook can be active for All Products, and only one for any given product. Turning a webhook on (or creating a new one) turns off the other webhook that covers the same products. Creating webhooks requires an active, paid LendAPI plan.

Handle events on your server

• Check the key. Compare the Authorization or X-API-KEY header with your webhook key, and reject requests that don't match. LendAPI doesn't sign payloads, so this key is how you confirm the sender.
• Respond fast. Return a 2xx as soon as you have stored the event, then do the heavy work in the background. Responses slower than 15 seconds count as failures and are retried.
• Deduplicate on event_id. Retries reuse the same event_id. Process each ID once.
• Don't rely on order. Events are delivered in the background and retries can arrive later, so events for one application may arrive out of order. Use stage and stage_label, or fetch the application, to get its current state.
• Use a separate endpoint for Sandbox so test traffic never reaches production systems.

Send webhooks from a flow

Separately from the workspace webhook above, a flow can send its own request with a Send Webhook step. This step posts the variables you select, plus the flow's ID and version, to any public HTTPS URL. It includes Idempotency-Key and X-Event-Id headers and makes up to 3 attempts within 15 seconds, retrying only connection errors, 429 and 5xx responses. See Flow Builder.

Permissions

Webhook settings are on the Webhook tab of the Settings module. Viewing needs view access to that tab, and adding, editing or turning webhooks on and off needs edit access. See Roles and Permissions.

Related guides