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

​
Testing your endpoint

Once a webhook is registered, call POST /webhooks/{id}/test to have Leaf fire a signed sample message at your URL on demand, so you can exercise your receiving and signature-verification code without waiting for a real event. The sample payload has "type": "test" and is meant for transport and signature checks, not event-schema validation. It is signed with the same X-Leaf-Signature scheme as real alerts, so verification code you write against the test works unchanged for live events. See Authentication for verification steps and Test a webhook for the endpoint details.
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

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 July 9, 2026