Webhooks

Koalafi webhooks let your system receive real-time notifications when a customer's lease application changes status. Instead of polling our API for updates, your endpoint receives an automatic HTTPS POST the moment an event occurs.

How It Works

You register a publicly accessible HTTPS endpoint with Koalafi.
When a supported event occurs (e.g., a lease is approved), Koalafi sends a signed POST request to your endpoint.
Your server validates the request and processes the update.

Event Types

Type	Description
`lease.changed`	Fired whenever a lease application transitions to a new status.

Additional event types will be introduced in future releases.

Payload Format

All webhook requests are POST with Content-Type: application/json.

{
  "type": "lease.changed",
  "version": "1",
  "timestamp": "2021-08-23T00:05:07-04:00",
  "data": {
    "leaseId": 123456,
    "leaseDisplayId": "4567-1",
    "orderIds": [
      "8f9f5ac6-2aa7-4fa1-a51d-21c87d917f3b"
    ],
    "newStatus": "approved",
    "previousStatus": "preApproved",
    "publicDealerId": "27365a1c-0228-443d-aae4-75faebaf8c70",
    "approvedAmount": "4600.00",
    "financedAmount": "3200.00",
    "customerSorID": 3456
  }
}

Field Reference

Field	Type	Description
`type`	string	Event type. Currently always `lease.changed`.
`version`	string	Payload schema version. Currently `"1"`.
`timestamp`	string	RFC 3339 timestamp of when the event occurred.
`data.leaseId`	integer	Koalafi's internal lease identifier.
`data.leaseDisplayId`	string	Human-readable lease identifier shown in the Koalafi portal.
`data.orderIds`	string[]	One or more Koalafi order IDs associated with this lease. Use these to match the event to orders in your system.
`data.newStatus`	string	The status the lease transitioned to.
`data.previousStatus`	string	The status the lease transitioned from.
`data.publicDealerId`	string	UUID identifying the dealer/merchant.
`data.approvedAmount`	string	The total amount the customer was approved for (decimal string).
`data.financedAmount`	string	The amount the customer financed (decimal string).
`data.customerSorID`	integer	Koalafi's system-of-record ID for the customer.

Security

Every request is signed using HTTP Message Signatures (RFC 9421) with an Ed25519 key pair. You should verify every incoming request before acting on it.

At a minimum, your handler should:

Verify the Content-Digest matches a SHA-256 hash of the raw request body.
Retrieve the current signing public key via the dealer.webhookConfig.signingKey GraphQL query.
Verify the Signature against the assembled signature base using the public key.
Reject requests where the signature is expired (check the expires parameter in Signature-Input).

For a step-by-step walkthrough, see Verifying Webhooks.