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

# Webhooks

> Outbound signed events to your HTTPS receiver. Webhooks are not Akhdar REST paths.

Webhooks are outbound requests to your receiver, not Akhdar REST paths. They are not authorized with `X-API-Key`. Akhdar delivers events to the HTTPS receiver configured for your environment.

## Envelope

Every webhook contains:

* `event_id`
* `delivery_id`
* `event_type`
* `event_version`
* `timestamp`
* `data`

## Verify signatures

Webhook requests include these required headers:

* `X-Akhdar-Signature`
* `X-Akhdar-Timestamp`
* `X-Akhdar-Event-ID`
* `X-Akhdar-Delivery-ID`

Compute HMAC-SHA256 over the exact `X-Akhdar-Timestamp` value, a period (`.`), and the exact raw request body bytes before JSON parsing or reformatting. The signature format is `v1=<hex>`. Accept timestamps only within five minutes before or after receipt.

## Delivery behavior

Delivery is at least once, so duplicates are possible. Process events idempotently using `event_id`. Retries keep the same `event_id` and use a new `delivery_id`.

Any HTTP `2xx` response is successful; no response body is required. A `429` response is retried according to `Retry-After`. Transient `408`, `5xx`, and timeout failures are retried. Non-transient `4xx` responses are not automatically retried.

## Partner actions

| Event                          | What to do                                                                                                                                   |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `impact.transaction.confirmed` | Treat the contribution as confirmed. Do not restore points. Recover contribution detail with the Contributions operations when needed.       |
| `impact.transaction.adjusted`  | Look up the contribution if you need current status. Do not treat this event as `failed`, and do not restore points from this payload alone. |
| `settlement.created`           | Record `settlement_id`. The payload is identifier-only.                                                                                      |
| `settlement.closed`            | Record that the settlement is closed. The payload is identifier-only.                                                                        |
| `environmental.status.updated` | Update fulfilment display from `status`. Do not claim funded, planted, or verified before that status is present.                            |

Schemas and examples for every event are in [API Reference](/api-reference).

## Event payload

### `impact.transaction.confirmed`

```json theme={null}
{
  "event_id": "evt_wh_01HZX8A1B2C3D4E5F6G7H8J9",
  "delivery_id": "dlv_01HZX8B2C3D4E5F6G7H8J9K0",
  "event_type": "impact.transaction.confirmed",
  "event_version": "1",
  "timestamp": "2026-08-13T12:05:00Z",
  "data": {
    "transaction_id": "txn_01HZX6M4N5P6Q7R8S9T0U1V2",
    "partner_event_id": "evt_contrib_01HZX5A1B2C3D4E5F6G7H8J9",
    "partner_order_ref": "ord_9f3c2a71",
    "status": "confirmed",
    "confirmed_at": "2026-08-13T12:05:00Z"
  }
}
```