Settlement batch webhooks

Settlement batch webhooks notify your HTTPS receiver when Akhdar creates or closes a settlement batch identified by settlement_id. They are outbound signed deliveries, not Akhdar REST paths. Use Webhooks for the shared envelope, signature verification, delivery semantics, and HTTP response expectations. Settlement batch events follow the same rules.

Settlement operations are not part of the partner server-to-server API documented here. Webhook data objects remain identifier-only; see each event in the API Reference.

`settlement_id`

settlement_id is the Akhdar-generated settlement batch identifier. Store it when you receive settlement.created so you can correlate a later settlement.closed for the same batch.

Events

Event	Purpose	What to do
`settlement.created`	A settlement batch was created for your Partner.	Record `settlement_id` (and `partner_id` for environment scoping). The payload is identifier-only.
`settlement.closed`	The settlement batch was explicitly closed.	Treat the batch as closed and immutable. Record `status: closed`. The payload is identifier-only plus `status`.

funded is an environmental fulfilment status, not a settlement batch status. Do not infer funding or planting outcomes from settlement batch webhooks alone.

Example payloads

settlement.created
settlement.closed

{
  "event_id": "evt_wh_01HZXAF6G7H8J9K0L1M2N3P4",
  "delivery_id": "dlv_01HZXAG7H8J9K0L1M2N3P4Q5",
  "event_type": "settlement.created",
  "event_version": "1",
  "timestamp": "2026-08-13T16:00:00Z",
  "data": {
    "settlement_id": "stl_01HZXAH8J9K0L1M2N3P4Q5R6",
    "partner_id": "partner_01HZX1A2B3C4D5E6F7G8H9J0"
  }
}

{
  "event_id": "evt_wh_01HZXBJ9K0L1M2N3P4Q5R6S7",
  "delivery_id": "dlv_01HZXBK0L1M2N3P4Q5R6S7T8",
  "event_type": "settlement.closed",
  "event_version": "1",
  "timestamp": "2026-08-13T18:00:00Z",
  "data": {
    "settlement_id": "stl_01HZXAH8J9K0L1M2N3P4Q5R6",
    "partner_id": "partner_01HZX1A2B3C4D5E6F7G8H9J0",
    "status": "closed"
  }
}

Field definitions and required properties are in the API Reference.

Verify, deliver, and deduplicate

Verify — Validate X-Akhdar-Signature using HMAC-SHA256 over X-Akhdar-Timestamp, ., and the raw request body. Enforce the five-minute timestamp window. See Webhooks.
Respond — Return any HTTP 2xx when you accept the event. No response body is required.
Deduplicate — Delivery is at-least-once. Process idempotently using event_id. Retries reuse event_id and send a new delivery_id.

A duplicate settlement.created or settlement.closed for the same event_id must not change your stored outcome.

API Reference

settlement.created — envelope and data schema
settlement.closed — envelope, data.status, and closed-batch semantics

Getting started

Guides

Resources

`settlement_id`

Events

Example payloads

Verify, deliver, and deduplicate

API Reference

​settlement_id

​Events

​Example payloads

​Verify, deliver, and deduplicate

​API Reference

`settlement_id`

Events

Example payloads

Verify, deliver, and deduplicate

API Reference