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

# Planting fulfilment batch webhooks

> Receive environmental.status.updated event version 2 for planting fulfilment batch lifecycle.

Planting fulfilment batch webhooks notify your HTTPS receiver when a **planting fulfilment batch** identified by `planting_fulfilment_batch_id` advances among the approved environmental states. They are outbound signed deliveries, not Akhdar REST paths.

Use [Webhooks](/webhooks) for the shared envelope, signature verification, delivery semantics, and HTTP response expectations. Planting fulfilment batch events follow the same rules.

<Note>
  Planting fulfilment batch list and detail operations are not part of the partner server-to-server API documented here. Webhook `data` remains `planting_fulfilment_batch_id`, `partner_id`, and `status`.
</Note>

## When this event fires

Akhdar delivers `environmental.status.updated` **event version `2`** when a planting fulfilment batch successfully advances among the approved environmental states:

`recorded` → `funding_pending` → `funded` → `planting_pending` → `planted` → `verified`

`funded` means the batch reached that environmental fulfilment status. It does not mean planted. Do not claim funded, planted, or verified to customers before that status is present.

New deliveries use event version `2`. Transaction-centric payload version `1` (`transaction_id` plus status) is retired for new deliveries.

Implementing-entity details, evidence counts, tree quantities, and individual-tree data are not included in this webhook payload.

## `planting_fulfilment_batch_id`

`planting_fulfilment_batch_id` is the Akhdar-generated planting fulfilment batch identifier. Store it when you receive the event so you can correlate later version `2` deliveries for the same batch.

`partner_id` scopes the batch to your Partner. `status` is the batch's current environmental fulfilment status.

## Relationship to contribution reads

Contribution recovery remains the partner server-to-server read path:

* `GET {baseUrl}/v1/impact-transactions?partner_event_id=`
* `GET {baseUrl}/v1/impact-transactions/{transaction_id}`

See [Recover a contribution](/contributions#recover-a-contribution).

Confirmed contributions may include a read-only `environmental_fulfilment` object. `status` on that object is the linked planting batch status when a batch is assigned. `planting_fulfilment_batch_id` may be present on that object when assigned. Authoritative tree totals are not on this webhook or on `environmental_fulfilment`.

## Events

| Event | Purpose | What to do |
| - | - | - |
| `environmental.status.updated` (`event_version` `2`) | A planting fulfilment batch advanced to a new environmental status. | Record `planting_fulfilment_batch_id`, `partner_id`, and `status`. Update fulfilment display from `status` only. |

## Example payload

```json theme={null}
{
  "event_id": "evt_wh_01HZXCL1M2N3P4Q5R6S7T8U9",
  "delivery_id": "dlv_01HZXCM2N3P4Q5R6S7T8U9V0",
  "event_type": "environmental.status.updated",
  "event_version": "2",
  "timestamp": "2026-08-13T19:00:00Z",
  "data": {
    "planting_fulfilment_batch_id": "pfb_01HZX6M4N5P6Q7R8S9T0U1V2",
    "partner_id": "partner_01HZX1A2B3C4D5E6F7G8H9J0",
    "status": "recorded"
  }
}
```

Required `data` fields: `planting_fulfilment_batch_id`, `partner_id`, and `status`.

## `X-Akhdar-Event-ID`

`X-Akhdar-Event-ID` is the logical event identifier. It must equal envelope `event_id`. It is stable across retries and redelivery. Use it for idempotent processing. `X-Akhdar-Delivery-ID` identifies one delivery attempt and changes on retry.

## Verify, deliver, and rotate

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). During an overlap window, current and previous signing secrets only (max two) may verify.
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` / `X-Akhdar-Event-ID`. Retries reuse `event_id` and send a new `delivery_id`.

A duplicate `environmental.status.updated` for the same `event_id` must not change your stored outcome.

Akhdar delivers this event to the same HTTPS receiver configured for your environment as the other approved webhook events. Webhook signing is separate from `X-API-Key`; API credential revocation does not by itself invalidate signature verification while the webhook secret remains valid.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.