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

# Alerts Overview

> Set up webhook-based alerts to receive real-time notifications when Leaf processes new data, credentials change, or satellite images become available.

Leaf Alerts notify you via webhooks when something changes, so you don't have to poll the API for updates. Alerts cover events from both Leaf's own processing pipeline and supported third-party providers.

## How it works

When you create a webhook, you provide three things:

1. A URL where Leaf sends HTTP POST requests.
2. A secret key Leaf uses to sign each request (HMAC SHA-256).
3. A list of event types you want to receive.

When a matching event occurs, Leaf sends a JSON payload to your URL. Your server should return a 2xx status code to acknowledge receipt.

After registration, Leaf immediately sends a confirmation message to your URL:

```json theme={null}
{
  "message": "confirmation of webhook upon registration"
}
```

If your server doesn't respond with a 2xx, Leaf retries at 1, 30, 60, and 240 minutes after the initial failure. You can check for missed deliveries using the failed calls endpoint.

<Warning>
  You cannot update a webhook in place. To change the URL or events, delete the existing webhook and create a new one. Keep the old URL running until the new webhook is confirmed.
</Warning>

## Recommended events

At a minimum, set up webhooks for:

* **Field events** (`fieldCreated`, `fieldBoundaryCreated`, `fieldBoundaryUpdated`) to track boundary changes.
* **Machine file events** (`providerFileProcessingFinished`, `uploadedFileProcessingFinished`) to know when new data is ready.
* **Operation events** (`operationCreated`, `operationProcessingFinished`) to react when field operations are available.
* **Credential events** (`credentialsUnauthenticated`, `credentialsLimitedPermission`) to catch broken provider connections early.

The full list of events and their payload schemas is on the [Events](/alerts/events) page.

## Retry policy

| Attempt | Delay after failure |
| ------- | ------------------- |
| 1       | 1 minute            |
| 2       | 30 minutes          |
| 3       | 60 minutes          |
| 4       | 240 minutes         |

After 4 failed attempts, the event is logged as a failed call. You can retrieve failed calls via `GET /webhooks/failed-calls`.

## Security

Every request includes an `X-Leaf-Signature` header containing a base64-encoded HMAC SHA-256 digest of the request body, signed with your secret. Always verify this signature before processing the payload. See [Authentication](/alerts/authentication) for implementation details.

<Note>
  Leaf runs on cloud infrastructure and does not have a fixed set of IP addresses for webhook delivery. If your network requires allow-listing, consider placing a reverse proxy or load balancer in a DMZ to receive webhooks and forward them internally.
</Note>

## Common use cases

* **React to new field operations**: Subscribe to `operationProcessingFinished` to trigger downstream workflows (yield analysis, report generation) as soon as data is ready.
* **Monitor provider credentials**: Subscribe to `credentialsUnauthenticated` and `credentialsLimitedPermission` to alert your support team when a grower's connection breaks.
* **Track boundary changes**: Subscribe to `fieldBoundaryCreated` and `fieldBoundaryUpdated` to keep your system in sync with provider-side field edits.
* **Automate satellite ingestion**: Subscribe to `newSatelliteImage` to process NDVI or NDRE imagery as soon as each satellite pass is clipped.

## What to do next

* [Events reference](/alerts/events) for all event types and payloads.
* [Authentication](/alerts/authentication) for signature verification code examples.
* [Alerts API Reference](/api-reference/alerts) for endpoint details.