Setting Up Your Webhook

Webhook endpoints are configured per merchant as part of your integration setup. Provide your HTTPS endpoint URL to your Koalafi integration contact. You can also provide a default webhook URL for your integration platform configuration — this will automatically register the endpoint for each merchant onboarded through your platform.

Implementing Your Endpoint

Requirements

Your endpoint must be reachable over HTTPS.
Return a 2xx response promptly. If processing takes time, acknowledge the request immediately and handle it asynchronously.
Verify the signature before acting on the payload.

Idempotency

Koalafi may deliver the same event more than once under certain failure conditions. Use the Message-Id header as an idempotency key — if you've already processed a message with that ID, skip the duplicate.

Recommended Handler Flow

1. Receive POST request
2. Verify Content-Digest (body hash)
3. Verify Signature
4. Check Message-Id — skip if already processed
5. Extract orderIds from payload
6. Look up matching order(s) in your system
7. Update order/contract status
8. Return 200 OK

Testing

Use your sandbox environment to test webhook delivery before going live. Send test events by advancing a lease application through its lifecycle in the sandbox. Your endpoint should receive a signed lease.changed event for each status transition.

If you need help testing or do not have sandbox access, contact your Koalafi integration contact.