EmbARC Webhook

This guide explains how to configure webhook endpoints, subscribe to supported events, verify delivery, and consume webhook payloads.

Webhooks Overview

Webhooks let your application receive near-real-time notifications when subscribed events occur. Each webhook points to an HTTPS endpoint that receives a JSON request body.

Each webhook can subscribe to one or more event types. When an event occurs, Embarc sends a signed HTTP request to the configured endpoint.

Configure a Webhook Endpoint

Webhook API Doc

Create a webhook with:

{
  "name": "Loan status updates",
  "endpointUrl": "https://example.com/webhooks/embarc",
  "enabled": true,
  "events": [
    {
      "eventType": "loan.status_changed"
    }
  ]
}

For installment.due, include the configured due-date offset:

{
  "eventType": "installment.due",
  "configuration": {
    "daysFromDueDate": -3
  }
}

daysFromDueDate accepts integer values from -365 through 365.

Supported Event Types

The top-level payload type is one of:

Category	Event type	Description
Loan	loan.created	A loan was created.
Loan	loan.updated	A loan was updated.
Loan	loan.status_changed	A loan status changed.
Installment	installment.due	A loan installment reached a configured due-date offset.
Tranche	tranche.due	A tranche reached its expected disbursement date.
Payment	payment.created	A payment was created.
Payment	payment.status_changed	A payment status changed.
Funding	funding.created	A funding record was created.
Funding	funding.status_changed	A funding status changed.
Lender payout	lender_payout.created	A lender payout was created.
Lender payout	lender_payout.status_changed	A lender payout status changed.
Payment instrument	payment_instrument.created	A payment instrument was created.
Payment instrument	payment_instrument.updated	A payment instrument was updated.
Payment instrument	payment_instrument.deleted	A payment instrument was deleted.
Payment instrument	payment_instrument.status_changed	A payment instrument status changed.
Client	client.created	A client was created.
Client	client.status_changed	A client status changed.

Event Payload Format

Every webhook request body uses this envelope:

{
  "id": 11,
  "type": "payment.status_changed",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:13.574088-04:00",
  "subject": {
    "type": "payment",
    "id": "42"
  },
  "data": {}
}

Field	Type	Description
id	number	Unique event identifier.
type	string	Public event type.
version	number	Payload contract version.
occurredAt	string	Offset-aware ISO-8601 timestamp for when the event occurred, formatted in the tenant time zone. Fractional seconds may be present.
subject.type	string	Main resource type for the event.
subject.id	string	Main resource identifier for the event.
data	object	Event-specific fields.

Created Event Payloads

Created events use the common envelope. The type identifies the resource that was created.

Event type	Subject type	Key data fields
loan.created	loan	entityId, sourceEventType
payment.created	payment	entityId, loanId, currentStatus, amount, effectiveDate
funding.created	funding	entityId, loanId, currentStatus, amount
lender_payout.created	lender_payout	entityId, loanId, currentStatus, amount
payment_instrument.created	payment_instrument	entityId, ownerType, ownerId, status, instrumentType
client.created	client	entityId, sourceEventType

Loan created:

{
  "id": 1387,
  "type": "loan.created",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:13.574088-04:00",
  "subject": {
    "type": "loan",
    "id": "5677"
  },
  "data": {
    "entityId": 5677,
    "sourceEventType": "LoanCreatedBusinessEvent"
  }
}

sourceEventType identifies the source notification that produced the webhook. Use the top-level type field as the stable subscription and routing value.

Payment created:

{
  "id": 10,
  "type": "payment.created",
  "version": 1,
  "occurredAt": "2026-07-10T11:25:02.798991-04:00",
  "subject": {
    "type": "payment",
    "id": "2331"
  },
  "data": {
    "entityId": 2331,
    "loanId": 2069,
    "currentStatus": "PENDING",
    "amount": 125.50,
    "effectiveDate": "2026-06-18"
  }
}

Funding created:

{
  "id": 1393,
  "type": "funding.created",
  "version": 1,
  "occurredAt": "2026-07-10T11:25:02.798991-04:00",
  "subject": {
    "type": "funding",
    "id": "5281"
  },
  "data": {
    "entityId": 5281,
    "loanId": 5678,
    "currentStatus": "SETTLED",
    "amount": 1000
  }
}

currentStatus is the funding status at the time the webhook event is captured. It is not guaranteed to be the initial REQUESTED state.

Payment instrument created:

{
  "id": 12,
  "type": "payment_instrument.created",
  "version": 1,
  "occurredAt": "2026-07-10T11:25:02.798991-04:00",
  "subject": {
    "type": "payment_instrument",
    "id": "91"
  },
  "data": {
    "entityId": 91,
    "ownerType": "CLIENT",
    "ownerId": 57,
    "status": "ACTIVE",
    "instrumentType": "BANK_ACCOUNT"
  }
}

Client created:

{
  "id": 1466,
  "type": "client.created",
  "version": 1,
  "occurredAt": "2026-07-10T16:43:03.057785-04:00",
  "subject": {
    "type": "client",
    "id": "2113"
  },
  "data": {
    "entityId": 2113,
    "sourceEventType": "ClientCreateBusinessEvent"
  }
}

Status Changed Event Payloads

Status-changed events use previousStatus and currentStatus when the source event includes both values.

Loan Status Changed

{
  "id": 1388,
  "type": "loan.status_changed",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:29.403142-04:00",
  "subject": {
    "type": "loan",
    "id": "5677"
  },
  "data": {
    "entityId": 5677,
    "previousStatus": "SUBMITTED_AND_PENDING_APPROVAL",
    "currentStatus": "REJECTED"
  }
}

Some loan.status_changed payloads contain a source event instead of previous and current statuses:

{
  "id": 1389,
  "type": "loan.status_changed",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:29.453039-04:00",
  "subject": {
    "type": "loan",
    "id": "5677"
  },
  "data": {
    "entityId": 5677,
    "sourceEventType": "LoanRejectedBusinessEvent"
  }
}

Consumers should treat previousStatus and currentStatus as optional for loan.status_changed.

Status values:

SUBMITTED_AND_PENDING_APPROVAL
APPROVED
ACTIVE
REJECTED
CLOSED_OBLIGATIONS_MET
CLOSED_RESCHEDULE_OUTSTANDING_AMOUNT
CLOSED_WRITTEN_OFF
TRANSFER_IN_PROGRESS
TRANSFER_ON_HOLD
WITHDRAWN_BY_CLIENT
OVERPAID

Payment Status Changed

{
  "id": 14,
  "type": "payment.status_changed",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:29.403142-04:00",
  "subject": {
    "type": "payment",
    "id": "2331"
  },
  "data": {
    "entityId": 2331,
    "loanId": 2069,
    "previousStatus": "PENDING",
    "currentStatus": "PROCESSING",
    "amount": 125.50,
    "effectiveDate": "2026-06-18"
  }
}

Status values:

PENDING
PROCESSING
SETTLED
RETURNED
FAILED

Funding Status Changed

{
  "id": 17,
  "type": "funding.status_changed",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:29.403142-04:00",
  "subject": {
    "type": "funding",
    "id": "5281"
  },
  "data": {
    "entityId": 5281,
    "loanId": 5678,
    "previousStatus": "REQUESTED",
    "currentStatus": "PROCESSING",
    "amount": 1000
  }
}

Status values:

REQUESTED
APPROVED
PROCESSING
SETTLED
POSTED
REJECTED
FAILED

Lender Payout Status Changed

{
  "id": 18,
  "type": "lender_payout.status_changed",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:29.403142-04:00",
  "subject": {
    "type": "lender_payout",
    "id": "301"
  },
  "data": {
    "entityId": 301,
    "loanId": 2069,
    "previousStatus": "PENDING",
    "currentStatus": "SETTLED",
    "amount": 4500
  }
}

Status values:

PENDING
REQUESTED
PROCESSING
SETTLED
FAILED

Payment Instrument Status Changed

{
  "id": 16,
  "type": "payment_instrument.status_changed",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:29.403142-04:00",
  "subject": {
    "type": "payment_instrument",
    "id": "91"
  },
  "data": {
    "entityId": 91,
    "ownerType": "CLIENT",
    "ownerId": 57,
    "previousStatus": "INACTIVE",
    "currentStatus": "ACTIVE",
    "instrumentType": "BANK_ACCOUNT"
  }
}

Payment instrument events cover both client-owned and counterparty-owned instruments. Use ownerType and ownerId to identify the owner.

Status values:

ACTIVE
INACTIVE
ERRORED

Scheduled Event Payloads

Installment Due

{
  "id": 15,
  "type": "installment.due",
  "version": 1,
  "occurredAt": "2026-07-10T11:11:29.403142-04:00",
  "subject": {
    "type": "loan_installment",
    "id": "4001"
  },
  "data": {
    "installmentId": 4001,
    "loanId": 2069,
    "clientId": 57,
    "installmentNumber": 3,
    "dueDate": "2026-06-22",
    "daysFromDueDate": -3,
    "outstandingAmount": "125.50",
    "currency": "USD",
    "loanExternalId": "loan-ext-2069"
  }
}

Delivery Expectations

Webhook receivers should:

Return a 2xx response after successfully accepting the event.
Process duplicate deliveries safely by using the event id.
Avoid relying on event delivery order across different resources.
Treat unknown optional fields as forward-compatible additions.