Skip to main content
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: 
{
  "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.
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.
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 page.

​
Retry policy

AttemptDelay after failure
11 minute
230 minutes
360 minutes
4240 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 for implementation details.
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.

​
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

Last modified on March 19, 2026