Overview
EASYCRED Webhooks deliver live HTTP POST event notifications directly to your backend server whenever a customer’s loan journey transitions through its lifecycle.Who Are Webhooks For?
Webhooks are supported and active for both Hosted (API_HOSTED) and Headless (API_HEADLESS) integrations:
- Hosted Integrations (
API_HOSTED): Webhooks are the primary recommended tracking mechanism. Because the customer completes all intermediary steps (offer selection, KYC verification, mandate setup, and e-signing) on EASYCRED’s hosted screens, webhooks notify your server in real-time as each milestone occurs and when the final sanction/disbursal is achieved—eliminating continuous polling. - Headless Integrations (
API_HEADLESS): In addition to active in-flight polling viaGET /v1/partner/journey/{journeyId}, webhooks serve as asynchronous alerts for milestone transitions and terminal states (journey.completed,journey.rejected,journey.failed).
webhooks:manageAuthentication: Standard HMAC headers (
x-api-key, x-signature, x-timestamp, x-nonce) are required for all webhook management endpoints.
Webhook Management Endpoints
1. Register a Webhook Subscription
Register an HTTPS endpoint to receive webhook notifications for specified events:
Response (HTTP 201 Created):
2. List Webhook Subscriptions
Retrieve all active webhook subscriptions for your partner account:3. Rotate Webhook Signing Secret
Issue a new HMAC signing secret for a subscription. Use this to rotate secrets periodically or if a secret has been compromised:4. Delete a Webhook Subscription
Permanently deactivate and delete a webhook subscription:Supported Webhook Events
The EASYCRED journey engine emits five canonical event types:Webhook Payload Format
EASYCRED sends HTTPPOST requests with Content-Type: application/json.
In-Flight Update (journey.updated)
Disbursal Milestone (journey.completed)
When the loan has been confirmed and disbursed by the lender, EASYCRED emits journey.completed with outcome: "COMPLETED" and the authoritative lender disbursal confirmation:
Payload Fields
Verifying Incoming Webhook Signatures
To ensure incoming requests genuinely originate from EASYCRED and have not been tampered with or replayed, EASYCRED signs every webhook payload.HTTP Headers Sent by EASYCRED
Canonical Signing String Format (v0)
EASYCRED uses length-prefixed canonical strings to prevent field injection: Example signing string:Verification Implementation (TypeScript / Node.js)
Verification Implementation (Python)
Delivery Guarantees & Best Practices
Idempotency
Idempotency
Store the incoming
id (e.g. evt_...) in your database. If EASYCRED retries delivery of an already processed event ID, return 200 OK immediately without re-executing business logic.5-Second Response Timeout
5-Second Response Timeout
Your webhook endpoint must return an HTTP
2xx response within 5 seconds. If your downstream processing takes longer, acknowledge the event immediately with 200 OK and process the event asynchronously on a background worker or job queue.Automatic Retries with Exponential Backoff
Automatic Retries with Exponential Backoff
If your endpoint returns an HTTP status outside
200-299 or times out, EASYCRED enqueues automatic retries with exponential backoff.State Reconciliation
State Reconciliation
For audit or end-of-day reconciliation, query your list of originated applications via
GET /api/v1/partner/leads or query individual status via GET /api/v1/partner/leads/{applicationId}/status.