> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhdar-sa.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use {baseUrl} for the environment-specific base URL provided to the partner integration team. Do not invent an API hostname.
> x-akhdar-* fields are publication provenance only. Do not treat them as partner integration instructions.

# Settlement batch webhooks

> Receive settlement.created and settlement.closed for settlement batch lifecycle.

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](/webhooks) for the shared envelope, signature verification, delivery semantics, and HTTP response expectations. Settlement batch events follow the same rules.

<Note>
  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](/api-reference).
</Note>

## `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

<Tabs>
  <Tab title="settlement.created">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>

  <Tab title="settlement.closed">
    ```json theme={null}
    {
      "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"
      }
    }
    ```
  </Tab>
</Tabs>

Field definitions and required properties are in the [API Reference](/api-reference).

## Verify, deliver, and deduplicate

1. **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](/webhooks#verify-signatures).
2. **Respond** — Return any HTTP `2xx` when you accept the event. No response body is required.
3. **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`](/api-reference/webhooks/settlementcreated) — envelope and `data` schema
* [`settlement.closed`](/api-reference/webhooks/settlementclosed) — envelope, `data.status`, and closed-batch semantics