Webhooks

Webhooks tell your system that a durable LendEasy event occurred. They are at-least-once notifications: duplicates, retries, and out-of-order delivery are normal integration conditions.

Create a subscription

curl -X POST "$BASE/v1/servicing/webhook-subscriptions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: portfolio-webhook-v1" \
  -d '{
    "url": "https://events.example.test/lendeasy",
    "eventTypes": [
      "payment.posted",
      "payment.returned",
      "funding.posted",
      "case.transitioned"
    ],
    "apiVersion": "2026-07-01",
    "description": "Portfolio event consumer"
  }'

The create response returns signingSecret exactly once. Store it as a secret; later reads expose only secretVersion.

Event envelope

{
  "eventId": "evt_PAY_81",
  "eventType": "payment.posted",
  "apiVersion": "2026-07-01",
  "occurredAt": "2026-09-15T14:22:08Z",
  "subject": {
    "type": "payment",
    "id": "9011"
  },
  "data": {
    "paymentId": 9011,
    "loanRef": "7204",
    "status": "POSTED",
    "amount": "517.14",
    "currency": "USD",
    "effectiveDate": "2026-09-12"
  }
}

The payload is a notification snapshot, not a substitute for an authorized API read when your workflow needs current state.

Verify before parsing business data

LendEasy signs the exact raw request bytes with the active secret. The delivery includes a timestamp, delivery ID, and versioned signature header. Verification order:

1. Read raw bytes without JSON reserialization.
2. Reject timestamps outside your replay window.
3. Compute HMAC over timestamp + separator + raw bytes.
4. Compare signatures in constant time against active overlap secrets.
5. Deduplicate eventId, then parse and enqueue.

Do not log the signature, secret, or unrestricted payload. During rotation, accept the old and new secret only until previousSecretExpiresAt.

Acknowledge quickly

Return any 2xx only after the verified event is durably queued or recorded, ideally within five seconds. Do not perform loan reads, provider calls, or heavy calculations before acknowledgement.

receive → verify → insert eventId uniquely → enqueue → 204
                                           └─ async business processing

Non-2xx responses and timeouts retry with increasing delay. A 2xx means your endpoint accepted responsibility; it does not mean your downstream workflow finished.

Idempotency and ordering

• Put a unique constraint on eventId.
• Track the last applied resource version for state projections.
• Ignore an older version after a newer version, but retain it for diagnostics.
• Fetch current state when a missing predecessor matters.
• Make side effects idempotent independently of webhook deduplication.

For example, payment.returned may reach one consumer before a delayed payment.posted delivery. The payment resource’s timeline determines truth, not arrival order.

Delivery operations

Event families

Published families include customer and consent lifecycle, loan and schedule changes, payment and return state, funding state, statements, servicing actions, restrictions, cases, tasks, interactions, promises, documents, merchant sales/remittances, and reconciliation exceptions. Subscribe narrowly and retrieve current resource state when needed.