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 |
| 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. |
| 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. |
| 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. |
| 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. |
| Event | Description |
|---|
newSatelliteImage | A new satellite image is available. |
satelliteSubscriptionFailed | A satellite subscription fails. |
| 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. |
| Event | Description |
|---|
workflowProcessingFinished | A workflow finishes processing. |
workflowProcessingFailed | A workflow fails processing. |
| Event | Description |
|---|
newIrrigationActivity | A new irrigation activity is available. |
newFieldIrrigationActivity | A new field irrigation activity is available. |
| 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'
Response
{
"id": "uuid",
"events": ["fieldCreated", "operationCreated"],
"name": "Field and operation listener",
"secret": "your-hmac-secret",
"url": "https://example.com/webhooks/leaf"
}
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}'
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'
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'
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}'
