Webhooks

Webhooks enable real-time notifications for key Lune events. Currently, Lune supports webhooks for the following event types:

Completion of transaction document processing.
Status change of a carbon credit order.

To set up a webhook:

Create and expose a webhook endpoint on your server to receive events.
Register the endpoint with Lune.

Pre-requisites

Complete the following setup steps before using this guide:

Generate an API key and authenticate your account.

1. Set up receiver endpoint

Create an HTTPS endpoint on your server to act as the webhook receiver, just like any standard web page or API endpoint.Make sure to note the public URL. You’ll need it to register the webhook with Lune in the next step.

Lune requires HTTPS endpoints, including for testing. Plain HTTP is not supported.

2. Register with Lune

You can register your webhook endpoint via the Lune Dashboard or using the API.

Using the dashboard

Go to the Developers tab in the Lune Dashboard.
Click New Live Webhook and enter your endpoint URL.

Webhooks registered through the dashboard receive events for all accounts and client accounts associated with your organisation.If Test mode is toggled on, the webhook will only receive test events.

Using the API

To register via API, send a POST request to the /webhooks endpoint with your url.

Webhooks created with test API keys will only receive test events.
Webhooks created with live API keys will receive live events.

Registering via the API gives you finer control, such as limiting the webhook to specific account IDs.For full details, see the API reference.

Sample request

Sample response

The response will include the webhook ID, URL, status (enabled or disabled), mode (test or live), any filtered account IDs, and the HMAC secret key used for verifying event authenticity (see below).

3. Process incoming events

Lune delivers events in account-specific order. All events for a given account ID are guaranteed to be delivered in the order they occurred.Events are sent in batches, and your receiver must return a 2xx status code within 30 seconds to acknowledge successful delivery. If an acknowledgment is not received, Lune will retry delivery until the event is acknowledged.Because events are delivered in order, a few unacknowledged events can block subsequent events in your webhook queue.Each request payload will contain several fields, including an event_type that identifies the nature of the event. You can find the list of possible event types below.

Authenticity and integrity

To ensure event authenticity, Lune signs every webhook payload and includes a signature in the Lune-HMAC header.timestamp=TIMESTAMP,organisation=ORGANISATION_ID,v1=HMAC_VALUE,...

TIMESTAMP

Unix epoch time when the payload was signed (can be used to check freshness).

ORGANISATION_ID

The ID of your organisation.

HMAC_VALUE

The SHA-256 HMAC signature of the payload.

Verify signature

In order to verify the authenticity of the request received by your endpoint, you'll need to verify the signature of the request. You can do this by extracting the:

TIMESTAMP from the Lune-HMAC header of the request,
body from the payload of the request,
secret returned from the API response when you first registered the endpoint.

Recompute the signature using the following formula:HMAC_SHA256(SECRET, TIMESTAMP + "." + BODY)Ensure the computed signature matches the HMAC_VALUE in the header of the request to complete your verification.

Idempotency

Lune follows an "at-least-once" delivery model, meaning events may be delivered multiple times. Your webhook receiver must be able to handle duplicate events safely.To support idempotency, you can:

Track the event_id: Ignore events that have already been processed.
Track sequence values: For each account, ignore events with a lower lexicographical sequence than the most recent one processed.