Alerts API - Leaf Documentation

Use these endpoints to create and manage webhooks that notify your application when field boundaries change, machine files finish processing, field operations are created, provider credentials expire, or satellite images are ready. For conceptual background, see Alerts Overview.

Base URL

https://api.withleaf.io/services/alerts/api/alerts

Endpoints

Description	Method	Path
Create a webhook	POST	`/webhooks`
Test a webhook	POST	`/webhooks/{id}/test`
Get a webhook	GET	`/webhooks/{id}`
Get all webhooks	GET	`/webhooks`
Get failed calls	GET	`/webhooks/failed-calls`
Delete a webhook	DELETE	`/webhooks/{id}`

You cannot update a webhook. To change an existing webhook, delete it and create a new one. Keep the previous URL running until the new webhook is confirmed.

On delivery failure, Leaf retries at 1, 30, 60, and 240 minutes after the initial attempt.

Available events

You can subscribe to any combination of these events: Credentials

Event	Description
`credentialsLimitedPermission`	Provider credentials have limited permissions.
`credentialsUnauthenticated`	Provider credentials are no longer authenticated.

Fields and boundaries

Event	Description
`fieldCreated`	A field is created.
`fieldUpdated`	A field is updated.
`fieldBoundaryCreated`	A field boundary is created.
`fieldBoundaryUpdated`	A field boundary is updated.
`fieldBoundaryDeleted`	A field boundary is deleted.
`mergedFieldCreated`	A merged field is created.
`mergedFieldUpdated`	A merged field is updated.

Machine files

Event	Description
`uploadedFileProcessingFinished`	An uploaded machine file finishes processing.
`uploadedFileProcessingFailed`	An uploaded machine file fails processing.
`providerFileProcessingFinished`	A provider-synced machine file finishes processing.
`providerFileProcessingFailed`	A provider-synced machine file fails processing.
`mergedFileProcessingFinished`	A merged file finishes processing.
`mergedFileProcessingFailed`	A merged file fails processing.
`automergedFileProcessingFinished`	An auto-merged field operation file finishes processing.
`automergedFileProcessingFailed`	An auto-merged field operation file fails processing.
`batchUploadProcessingFinished`	All files in a batch upload have finished processing.
`batchUploadProcessingFailed`	A batch upload fails before any files are processed (e.g., unsupported format).

Field operations

Event	Description
`operationCreated`	A field operation is created.
`operationUpdated`	A field operation is updated.
`operationProcessingFinished`	A field operation finishes processing.
`operationProcessingFailed`	A field operation fails processing.

Satellite imagery

Event	Description
`newSatelliteImage`	A new satellite image is available.
`satelliteSubscriptionFailed`	A satellite subscription fails.

Assets (Beta)

Event	Description
`machineCreated`	A machine is created.
`machineUpdated`	A machine is updated.
`machineDeleted`	A machine is deleted.
`implementCreated`	An implement is created.
`implementUpdated`	An implement is updated.
`operatorCreated`	An operator is created.
`operatorUpdated`	An operator is updated.

Workflows (Beta)

Event	Description
`workflowProcessingFinished`	A workflow finishes processing.
`workflowProcessingFailed`	A workflow fails processing.

Irrigation

Event	Description
`newIrrigationActivity`	A new irrigation activity is available.
`newFieldIrrigationActivity`	A new field irrigation activity is available.

Provider organizations

Event	Description
`providerOrganizationCreated`	A provider organization is created.
`providerOrganizationBlocked`	A provider organization is blocked.
`providerOrganizationRemoved`	A provider organization is removed.

You cannot register two webhooks that listen to the same event. Attempting to do so returns a 400 response with error eventRegisteredTwice.

Create a webhook

POST /webhooks Creates a webhook and begins delivering matching events immediately.

Request body

Parameter	Type	Required	Description
events	string[]	Yes	Array of event names from the available events list.
name	string	Yes	Display name for the webhook.
secret	string	Yes	Secret used for HMAC signature verification of payloads.
url	string	Yes	A valid HTTP(S) URL where Leaf delivers event payloads.

Request

curl -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "events": ["fieldCreated", "operationCreated"],
    "name": "Field and operation listener",
    "secret": "your-hmac-secret",
    "url": "https://example.com/webhooks/leaf"
  }' \
  'https://api.withleaf.io/services/alerts/api/alerts/webhooks'

import requests

TOKEN = "YOUR_TOKEN"
headers = {"Authorization": f"Bearer {TOKEN}"}

payload = {
    "events": ["fieldCreated", "operationCreated"],
    "name": "Field and operation listener",
    "secret": "your-hmac-secret",
    "url": "https://example.com/webhooks/leaf",
}

response = requests.post(
    "https://api.withleaf.io/services/alerts/api/alerts/webhooks",
    headers=headers,
    json=payload,
)
print(response.json())

const axios = require("axios");

const TOKEN = "YOUR_TOKEN";
const headers = { Authorization: `Bearer ${TOKEN}` };

const payload = {
  events: ["fieldCreated", "operationCreated"],
  name: "Field and operation listener",
  secret: "your-hmac-secret",
  url: "https://example.com/webhooks/leaf",
};

axios
  .post("https://api.withleaf.io/services/alerts/api/alerts/webhooks", payload, { headers })
  .then((res) => console.log(res.data))
  .catch(console.error);

Response

{
  "id": "uuid",
  "events": ["fieldCreated", "operationCreated"],
  "name": "Field and operation listener",
  "secret": "your-hmac-secret",
  "url": "https://example.com/webhooks/leaf"
}

Test a webhook

POST /webhooks/{id}/test Immediately delivers a signed sample message to the webhook’s registered URL. Use it to exercise your receiving and signature-verification code end to end, on demand, without waiting for a real event.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	Yes	UUID of the webhook.

No request body is required.

Request

curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/alerts/api/alerts/webhooks/2bcfa549-8ab4-4440-b9b5-6a5e1a0b62a7/test'

import requests

TOKEN = "YOUR_TOKEN"
WEBHOOK_ID = "2bcfa549-8ab4-4440-b9b5-6a5e1a0b62a7"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.post(
    f"https://api.withleaf.io/services/alerts/api/alerts/webhooks/{WEBHOOK_ID}/test",
    headers=headers,
)
print(response.status_code)

const axios = require("axios");

const TOKEN = "YOUR_TOKEN";
const WEBHOOK_ID = "2bcfa549-8ab4-4440-b9b5-6a5e1a0b62a7";
const headers = { Authorization: `Bearer ${TOKEN}` };

axios
  .post(
    `https://api.withleaf.io/services/alerts/api/alerts/webhooks/${WEBHOOK_ID}/test`,
    null,
    { headers },
  )
  .then((res) => console.log(res.status))
  .catch(console.error);

Delivered payload

Leaf sends the following POST to your registered URL, with Content-Type: application/json and an X-Leaf-Signature header:

{"type": "test", "timestamp": "2026-07-09T18:02:59.438203996Z", "webhookId": "uuid"}

This payload is a fixed shape with "type": "test". Real events use their own type (for example, batchUploadProcessingFinished) and fields, so /test validates transport and signature verification, not the event schema. The secret and X-Leaf-Signature scheme are identical to production alerts, so verification code written against /test works unchanged once live events arrive. See Authentication for the HMAC verification steps.

Response

Returns 200 OK if your endpoint accepted the sample message. If your endpoint returns an error, the call responds with a status that reflects what your endpoint returned, which is useful for debugging delivery and signature handling.

Get a webhook

GET /webhooks/{id} Returns a single webhook by its ID.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	Yes	UUID of the webhook.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/alerts/api/alerts/webhooks/{id}'

import requests

TOKEN = "YOUR_TOKEN"
headers = {"Authorization": f"Bearer {TOKEN}"}

webhook_id = "WEBHOOK_UUID"
response = requests.get(
    f"https://api.withleaf.io/services/alerts/api/alerts/webhooks/{webhook_id}",
    headers=headers,
)
print(response.json())

const axios = require("axios");

const TOKEN = "YOUR_TOKEN";
const headers = { Authorization: `Bearer ${TOKEN}` };

const webhookId = "WEBHOOK_UUID";
axios
  .get(`https://api.withleaf.io/services/alerts/api/alerts/webhooks/${webhookId}`, { headers })
  .then((res) => console.log(res.data))
  .catch(console.error);

Response

{
  "id": "uuid",
  "events": ["fieldCreated", "operationCreated"],
  "name": "Field and operation listener",
  "secret": "your-hmac-secret",
  "url": "https://example.com/webhooks/leaf"
}

Get all webhooks

GET /webhooks Returns all webhooks registered for the API owner.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/alerts/api/alerts/webhooks'

import requests

TOKEN = "YOUR_TOKEN"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.get(
    "https://api.withleaf.io/services/alerts/api/alerts/webhooks",
    headers=headers,
)
print(response.json())

const axios = require("axios");

const TOKEN = "YOUR_TOKEN";
const headers = { Authorization: `Bearer ${TOKEN}` };

axios
  .get("https://api.withleaf.io/services/alerts/api/alerts/webhooks", { headers })
  .then((res) => console.log(res.data))
  .catch(console.error);

Response

[
  {
    "id": "uuid",
    "events": ["fieldCreated", "operationCreated"],
    "name": "Field and operation listener",
    "secret": "your-hmac-secret",
    "url": "https://example.com/webhooks/leaf"
  }
]

Get failed calls

GET /webhooks/failed-calls Returns a paginated list of failed webhook delivery attempts when any exist. Use the nextPageToken value from a response to fetch the next page. If no failed calls are available for the API owner, this endpoint returns 404.

Parameters

Parameter	Type	Location	Required	Description
nextPageToken	string	query	No	Token returned in the previous response to retrieve the next page.

Request

curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/alerts/api/alerts/webhooks/failed-calls'

# To fetch the next page:
curl -X GET \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/alerts/api/alerts/webhooks/failed-calls?nextPageToken=TOKEN_VALUE'

import requests

TOKEN = "YOUR_TOKEN"
headers = {"Authorization": f"Bearer {TOKEN}"}

response = requests.get(
    "https://api.withleaf.io/services/alerts/api/alerts/webhooks/failed-calls",
    headers=headers,
)
data = response.json()
print(data)

# Fetch next page if available
next_token = data.get("nextPageToken")
if next_token:
    response = requests.get(
        "https://api.withleaf.io/services/alerts/api/alerts/webhooks/failed-calls",
        headers=headers,
        params={"nextPageToken": next_token},
    )
    print(response.json())

const axios = require("axios");

const TOKEN = "YOUR_TOKEN";
const headers = { Authorization: `Bearer ${TOKEN}` };

axios
  .get("https://api.withleaf.io/services/alerts/api/alerts/webhooks/failed-calls", { headers })
  .then((res) => {
    console.log(res.data);
    // Use res.data.nextPageToken for the next page
  })
  .catch(console.error);

Response

{
  "items": [
    {
      "apiOwner": "your-api-owner",
      "createdAt": "2026-01-15T12:16:30Z",
      "url": "https://example.com/webhooks/leaf",
      "status": 502,
      "response": "Bad Gateway",
      "requestBody": "{\"leafUserId\":\"uuid\",\"fileId\":\"uuid\",\"type\":\"automergedFileProcessingFinished\",\"timestamp\":\"2026-01-15T12:16:27Z\"}"
    },
    {
      "apiOwner": "your-api-owner",
      "createdAt": "2026-01-15T14:10:05Z",
      "url": "https://example.com/webhooks/leaf",
      "connectionError": "ConnectionError: Remote end closed connection without response"
    }
  ],
  "nextPageToken": "eyJsYXN0..."
}

Delete a webhook

DELETE /webhooks/{id} Deletes a webhook. Returns 204 No Content on success. Leaf stops delivering events for this webhook immediately.

Parameters

Parameter	Type	Location	Required	Description
id	string	path	Yes	UUID of the webhook.

Request

curl -X DELETE \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://api.withleaf.io/services/alerts/api/alerts/webhooks/{id}'

import requests

TOKEN = "YOUR_TOKEN"
headers = {"Authorization": f"Bearer {TOKEN}"}

webhook_id = "WEBHOOK_UUID"
response = requests.delete(
    f"https://api.withleaf.io/services/alerts/api/alerts/webhooks/{webhook_id}",
    headers=headers,
)
print(response.status_code)  # 204

const axios = require("axios");

const TOKEN = "YOUR_TOKEN";
const headers = { Authorization: `Bearer ${TOKEN}` };

const webhookId = "WEBHOOK_UUID";
axios
  .delete(`https://api.withleaf.io/services/alerts/api/alerts/webhooks/${webhookId}`, { headers })
  .then((res) => console.log(res.status))  // 204
  .catch(console.error);

​Base URL

​Endpoints

​Available events

​Create a webhook

​Request body

​Request

​Response

​Test a webhook

​Parameters

​Request

​Delivered payload

​Response

​Get a webhook

​Parameters

​Request

​Response

​Get all webhooks

​Request

​Response

​Get failed calls

​Parameters

​Request

​Response

​Delete a webhook

​Parameters

​Request

Base URL

Endpoints

Available events

Create a webhook

Request body

Request

Response

Test a webhook

Parameters

Request

Delivered payload

Response

Get a webhook

Parameters

Request

Response

Get all webhooks

Request

Response

Get failed calls

Parameters

Request

Response

Delete a webhook

Parameters

Request