Skip to main content

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 via GET /v1/partner/journey/{journeyId}, webhooks serve as asynchronous alerts for milestone transitions and terminal states (journey.completed, journey.rejected, journey.failed).
Required Scope: webhooks:manage
Authentication: 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:
Request Body:
Response (HTTP 201 Created):
Store the Webhook Signing Secret Immediately: The secret is returned once only upon creation. It is never returned again on list or inspect endpoints. You need this secret to verify signatures of incoming webhook calls.

2. List Webhook Subscriptions

Retrieve all active webhook subscriptions for your partner account:
Response (HTTP 200 OK):

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:
Response (HTTP 200 OK):

4. Delete a Webhook Subscription

Permanently deactivate and delete a webhook subscription:
Response (HTTP 200 OK):

Supported Webhook Events

The EASYCRED journey engine emits five canonical event types:

Webhook Payload Format

EASYCRED sends HTTP POST 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: signingString="v0:"+len(ts)+":"+ts+":"+len(nonce)+":"+nonce+":"+rawBody\text{signingString} = \text{"v0:"} + \text{len(ts)} + \text{":"} + \text{ts} + \text{":"} + \text{len(nonce)} + \text{":"} + \text{nonce} + \text{":"} + \text{rawBody} Example signing string:

Verification Implementation (TypeScript / Node.js)

Verification Implementation (Python)

CRITICAL — Raw Body Bytes: Always calculate the signature over the raw unparsed JSON string bytes directly from the HTTP request stream. Never re-serialize a parsed JSON object with JSON.stringify(), as key ordering and whitespace differences will invalidate the signature.

Delivery Guarantees & Best Practices

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.
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.
If your endpoint returns an HTTP status outside 200-299 or times out, EASYCRED enqueues automatic retries with exponential backoff.
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.