Status Change Webhooks

Biz Core fires a status change webhook whenever a Lead, Application, Loan, or Transaction record changes status. Each event pushes a JSON payload to your configured endpoint.

For setup, configuration, and best practices, see Setting Up Webhooks.

Event Types

Event	Record	Purpose
Lead Status Changed	Lead (`BCB...`)	Fires on any Lead status change. See Lead Lifecycle for status values.
Application Status Changed	Application (`BCA...`)	Fires on any Application status change. See Application Statuses below.
Loan Status Changed	Loan (`BCL...`)	Fires on any Loan status change. See Loan Statuses below.
Transaction Status Change	Transaction	Fires when an individual payment transaction's status changes. See Transaction Status Change below.

The External Decision Engine push is a separate webhook pattern that requires a response contract — see External Decision Engine.

For status transition diagrams and business rules, see Records & Statuses in the user knowledge base.

Payload Structure — Record Status Webhooks

The schema in this section applies to Lead Status Changed, Application Status Changed, and Loan Status Changed events. The Transaction Status Change webhook has its own compact structure, documented in its section below.

Every record-status payload contains three groups of fields:

Event-specific fields — identifiers and status for the record type that triggered the event.
Customer fields — common to all events.
Address & contact fields — common to all events.

If a customer field is not stored on the record, the payload still fires but the field will be null or empty.

Common Customer Fields (all events)

Field	Type	Description
`subscriptionId`	string (UUID)	Your unique subscription identifier.
`customerRef`	string	The customer record's reference number.
`firstName`	string	Customer first name.
`lastName`	string	Customer surname.
`dateOfBirth`	string (ISO 8601)	Customer date of birth.
`companyName`	string \| null	Company name (for business loans only).
`tradingName`	string \| null	Trading name (for business loans only).
`emailAddress`	string	Customer email.
`phoneNumber`	string	Customer phone number.
`phoneTypeId`	number	`0` = Residential, `1` = Mobile, `2` = Business.
`phoneType`	string	Human-readable phone type.
`address`	object	Customer address (see below).
`customerTags`	array<string>	Tags applied to the customer record.
`leadIdentifiers`	string (JSON)	Custom URL identifiers captured at lead intake.
`gaClientID`	string \| null	Google Analytics Client ID, if captured.

Address Object

Field	Description
`premise`	Unit / level / suite number, if applicable.
`streetAddress`	Street address.
`postalCode`	Post code.
`locality`	Suburb.
`administrativeArea`	State or territory.
`country`	Country.
`contactId`	Unique ID for this address record.

Status History

Lead and Application payloads include a statusHistory array containing prior status transitions for the record, in chronological order. Each entry captures the transition's identifier, the status the record moved into at that point, the timestamp, and the user (or system) that triggered the change.

ℹ️ Note: Loan Status Changed does not include a statusHistory array.

The entry field names vary by event type:

Event	Transition ID field	Status ID field	Status name field
Lead Status Changed	`leadStatusTransitionId`	`leadStatusId`	`leadStatus`
Application Status Changed	`applicationStatusTransitionId`	`applicationStatusId`	`applicationStatus`

Common fields in each entry:

Field	Description
`*StatusTransitionId`	Unique ID of this transition.
`*Id`	The record ID (same as the top-level record ID).
`*StatusId`	Numeric ID of the status entered at this transition. Useful if you prefer integer comparisons over string matching.
`*Status`	String name of the status entered at this transition.
`statusDate`	ISO 8601 timestamp of when the transition occurred.
`userId`	UUID of the user who triggered the transition, or system identifier for automatic transitions.
`user`	Human-readable identifier (typically the user's email).

ℹ️ Note: The top-level statusDate and the entries inside statusHistory may use different timezone offsets. Treat both as ISO 8601 with explicit offset rather than assuming a fixed zone.

Lead Status Changed

Event-specific fields

Field	Description
`leadId`	Unique ID of the Lead.
`leadRef`	Biz Core reference number for the Lead.
`leadStatus`	Current status of the Lead. One of: Incomplete, Complete, Converted, Dismissed.
`statusDate`	ISO 8601 timestamp with offset for when the current status was entered.
`loanRef`	Reference of the Loan this Lead converted to, if applicable.
`loanApplicationRef`	Reference of the Application this Lead converted to, if applicable.
`leadSource`	Value from the `leadSource=` URL parameter.
`leadCampaign`	Value from the `campaign=` URL parameter.
`leadMedium`	Value from the `leadMedium=` URL parameter.
`statusHistory`	Array of prior status transitions for this Lead. See Status History above for the entry schema.

Example payload

{
  "subscriptionId": "1a468f14-605b-4550-8f0f-10efd6ff5d83",
  "leadId": "ad7a9c60-eb51-4c6c-8edf-a02b2b2181ac",
  "leadRef": "lead-ref",
  "leadStatus": "Converted",
  "statusDate": "2026-05-15T11:52:59.0434041+10:00",
  "loanRef": null,
  "customerRef": "customer-ref",
  "loanApplicationRef": "application-ref",
  "firstName": "Simon",
  "lastName": "Smith",
  "dateOfBirth": "1990-01-01T00:00:00",
  "emailAddress": "[email protected]",
  "phoneNumber": "0412345678",
  "phoneTypeId": 1,
  "phoneType": "Mobile",
  "address": {
    "premise": "Unit 33",
    "streetAddress": "22 Queen Street",
    "postalCode": "2063",
    "locality": "Sydney",
    "administrativeArea": "NSW",
    "country": "Australia",
    "contactId": "7918e32a-e6a2-41c3-b73d-144d538cb374"
  },
  "customerTags": ["Worker"],
  "leadSource": "lead-source",
  "leadCampaign": "lead-campaign",
  "leadMedium": "lead-medium",
  "leadIdentifiers": "[]",
  "gaClientID": "XYXA",
  "statusHistory": [
    {
      "leadStatusTransitionId": "fe83c80f-c708-46b7-8a01-a09c1fa7a6c9",
      "leadId": "ad7a9c60-eb51-4c6c-8edf-a02b2b2181ac",
      "leadStatusId": 0,
      "leadStatus": "Incomplete",
      "statusDate": "2026-05-13T01:52:59.0434068+00:00",
      "userId": "a6c79c35-de60-4d00-8abb-67603b270a1c",
      "user": "[email protected]"
    }
  ]
}

Application Status Changed

Application Statuses

The loanApplicationStatus field uses these string values:

Status	Numeric ID	Meaning
`New`	0	Application received and in the queue to be assessed.
`Processing`	1	Application is currently being assessed.
`Pending`	2	Something is delaying the application — contact the lender for details.
`Review`	3	Assessed and a second review is required.
`Withdrawn`	4	Application has been withdrawn.
`Declined`	5	Application has been declined. `declinedWithdrawnReason` will be populated.
`Approved`	6	Application approved — the lender will contact the customer to proceed with settlement.
`Complete`	7	Application approved and funds disbursed. No further actions required.
`Conditionally Approved`	8	Approved with specific conditions that must be met before final approval can be granted.

The numeric applicationStatusId is available in statusHistory entries for clients that prefer integer comparison over string matching.

Event-specific fields

Field	Description
`loanApplicationId`	Unique ID of the Application.
`loanApplicationRef`	Biz Core reference number for the Application.
`loanApplicationStatus`	Current status of the Application. See Application Statuses above.
`declinedWithdrawnReason`	Reason supplied if Application was declined or withdrawn.
`statusDate`	ISO 8601 timestamp with offset for when the current status was entered.
`loanRef`	Reference of the Loan this Application converted to, if applicable.
`leadRef`	Reference of the Lead this Application originated from, if applicable.
`statusHistory`	Array of prior status transitions for this Application. See Status History above for the entry schema.

Example payload

{
  "subscriptionId": "aacf32a8-de05-4edd-a31a-2dfa50f70eca",
  "loanApplicationId": "3f0432e1-6bea-4dca-acc0-2458fb690edb",
  "loanApplicationRef": "application-ref",
  "loanApplicationStatus": "Declined",
  "declinedWithdrawnReason": "Not enough credit",
  "statusDate": "2026-05-15T11:52:59.0433301+10:00",
  "loanRef": "loan-ref",
  "customerRef": "customer-ref",
  "firstName": "Jerry",
  "lastName": "Kate",
  "dateOfBirth": "1990-01-01T00:00:00",
  "companyName": "OnePlusOne Pty Ltd",
  "tradingName": "OnePlusOne",
  "emailAddress": "[email protected]",
  "phoneNumber": "0400000000",
  "phoneTypeId": 0,
  "phoneType": "Residential",
  "address": { "...": "see Address Object above" },
  "customerTags": ["Student"],
  "leadRef": "lead-ref",
  "leadIdentifiers": "[]",
  "gaClientID": "XYXSA",
  "statusHistory": [
    {
      "applicationStatusTransitionId": "e7cf9889-1de9-42a0-8796-a8ffb10e4a4f",
      "applicationId": "3f0432e1-6bea-4dca-acc0-2458fb690edb",
      "applicationStatusId": 0,
      "applicationStatus": "New",
      "statusDate": "2026-05-12T01:52:59.0433374+00:00",
      "userId": "39cc9012-4552-4bd3-a3f8-fb4b98dd11ca",
      "user": "[email protected]"
    }
  ]
}

Loan Status Changed

Loan Statuses

Sourced from LoanStatusEnum in the Biz Core C# codebase. The serialized string is the Name attribute value, not the C# member name.

Status	Meaning	State
`Contract`	A contract is waiting to be signed.	Pre-active
`Ready`	Funds are waiting to be disbursed.	Pre-active
`Active`	Loan is active and repayments are up to date.	Open
`Arrears`	Customer is behind on scheduled repayments.	Open
`Managed`	Being managed by the team due to special circumstances.	Open
`Hardship Application`	Hardship assistance request submitted and under review.	Open
`Hardship`	Under financial hardship arrangement with special management.	Open
`Collections`	Fallen too far behind — entered collections proceedings, default may be listed on credit file.	Open
`Collections: Managed`	In collections and being actively managed by the team.	Open
`Settled`	Loan settled in full.	Closed
`Refinanced`	Refinanced by a new loan.	Closed
`Written Off`	Loan was written off.	Closed
`Sold`	Sold to a third party.	Closed
`Cancelled`	Loan was voided — never progressed to `Active`.	Closed

Event-specific fields

Field	Description
`loanId`	Unique ID of the Loan.
`loanRef`	Biz Core reference number for the Loan.
`loanStatus`	Current status of the Loan. See Loan Statuses above.
`statusDate`	ISO 8601 timestamp with offset for when the current status was entered.
`loanApplicationRef`	Reference of the Application this Loan originated from, if applicable.
`customerRef`	The customer record's reference number.
`leadRef`	Reference of the Lead this Loan originated from, if applicable.

Example payload

{
  "subscriptionId": "fe081786-ac17-4704-8824-e275c070eb8f",
  "loanId": "ead0a78c-8d5d-4ca1-8f31-590addcdd1e5",
  "loanRef": "BCL001001A",
  "loanStatus": "Active",
  "statusDate": "2026-05-15T11:52:59.3534466+10:00",
  "loanApplicationRef": "BCA001001A",
  "customerRef": "BCC001001A",
  "leadRef": "BCB001001A",
  "firstName": "Test",
  "lastName": "Customer",
  "dateOfBirth": "1990-01-01T00:00:00",
  "companyName": null,
  "tradingName": null,
  "emailAddress": "[email protected]",
  "phoneNumber": "0400000000",
  "phoneTypeId": 1,
  "phoneType": "Mobile",
  "address": {
    "premise": null,
    "streetAddress": "123 Main Street",
    "postalCode": "2000",
    "locality": "Sydney",
    "administrativeArea": "NSW",
    "country": "Australia",
    "contactId": "7918e32a-e6a2-41c3-b73d-144d538cb374"
  },
  "customerTags": [],
  "leadIdentifiers": "[]",
  "gaClientID": null
}

Transaction Status Change

Fires whenever an individual payment transaction's status changes — e.g. from Scheduled to Processing, from Processing to Successful, or from Successful to Declined (a late rejection).

This is the webhook to subscribe to when implementing the recommendation in Payment Module — Step 6.

Payload structure

This event uses its own compact schema — none of the customer/address/status-history fields above apply.

Field	Description
`subscriptionId`	Your unique subscription identifier.
`transactionAgreementId`	UUID of the parent transaction agreement.
`transactionAgreementRef`	Biz Core reference for the agreement (`BCP...`).
`customerId`	UUID of the customer.
`customerRef`	Biz Core customer reference (`BCC...`).
`transactionId`	UUID of the individual transaction.
`transactionRef`	Biz Core transaction reference.
`transactionDate`	ISO 8601 timestamp of the transaction.
`transactionAmount`	Decimal amount of the transaction.
`transactionStatus`	New status of the transaction. See Transaction Statuses in the Payment Module docs.
`declineReason`	If `transactionStatus` is `Declined` or `Late Rejection`, the bank or system reason code (e.g. `AccountClosed`). Null otherwise.

Example payload

{
  "subscriptionId": "2467699f-33df-49eb-95e0-f8d1b09aca6a",
  "transactionAgreementId": "1bee0bf9-5fa9-4cb2-88b1-c54d6bf95c7f",
  "transactionAgreementRef": "agreement-ref",
  "customerId": "82a60f60-e4b7-45da-a628-3bc0baf78e38",
  "customerRef": "customer-ref",
  "transactionId": "c59ccc18-ab8e-4ff8-84a7-c1be4aaa4ad6",
  "transactionRef": "transaction-ref",
  "transactionDate": "2026-05-15T12:05:11.563689+10:00",
  "transactionAmount": 12.33,
  "transactionStatus": "Declined",
  "declineReason": "AccountClosed"
}

ℹ️ Decline reason codes. AccountClosed is one example; the full enumeration includes codes such as account-closed, invalid-account, insufficient-funds, payment-stop, etc. Refer to the API reference or test in UAT for the complete set.

For best practices (idempotency, source verification, monitoring), see Setting Up Webhooks.