Alerts Endpoints

All HTTP methods should be prepended by this service's endpoint:

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

This service has the following endpoints available:

DescriptionEndpoints
Create a webhookPOST /webhooks
Get a webhookGET /webhooks/{id}
Get all webhooksGET /webhooks
Get failed calls for webhooksGET /webhooks/failed-calls
Delete a webhookDELETE /webhooks/{id}

Note that currently it's not possible to update a Webhook with a single request. If you want to update an existing Webhook resource, you have to delete it first and then recreate it. In doing so, be aware that if the update changes the Webhook URL, it's recommended that you keep the previous URL up and running until you get the response from the recreation request (POST).

For easy testing of these endpoints, we recommend using our Postman collection.

To understand how to verify if an incoming request comes from Leaf, see the Authentication section.


Create a webhook

 POST /webhooks

Creates a webhook resource, specifying which events you want to be notified about and where (server URL). The webhook will begin receiving events immediately after it is created.

It's not possible to create different webhooks that listen to the same events. For example, if you have already registered a webhook listening for newSatelliteImages and try to register another one, you'll get a 400 response with error eventRegisteredTwice.

Request body

ParameterTypeDescription
eventsenum name of the event typeThey are defined in the "Events" section of the services chapters (e.g. newSatelliteImage)
namestringThe name of your webhook
secretstringThe secret used for HMAC authentication. We sign payload with this secret. See more here
urla valid HTTP URL stringThe address of your webhook server

The allowed keys to be filled in events are:

  • credentialsLimitedPermission, credentialsUnauthenticated, fieldCreated, fieldBoundaryCreated, fieldBoundaryUpdated, uploadedFileProcessingFinished, uploadedFileProcessingFailed, providerFileProcessingFinished, providerFileProcessingFailed, mergedFileProcessingFinished, mergedFileProcessingFailed, automergedFileProcessingFinished, automergedFileProcessingFailed, operationCreated, operationUpdated, operationProcessingFinished, newSatelliteImage, machineCreated, machineUpdated, machineDeleted

To see the detailed description of each of these events, click here.

Example in JSON:

{
"events": [
"newSatelliteImage"
],
"name": "Satellite images listener",
"secret": "mRyT257XpFWX",
"url": "https://yourwebhook.com/leaf/satellite"
}

Request example

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d 'Your paylaod as specified above'
'https://api.withleaf.io/services/alerts/api/alerts/webhooks'

Response

It returns a JSON containing information about the webhook created.

{
"id": "UUID",
"events": [
"newSatelliteImage"
],
"name": "Satellite images listener",
"secret": "mRyT257XpFWX",
"url": "https://agtech.com/leaf/satellite"
}

If you need to test your endpoint, here is a request example so you can simulate the validation Leaf will do.

curl -X POST \
-H 'Content-Type: application/json' \
-H 'accept: */*' \
-d '{"message" : "confirmation of webhook upon registration"}'
'your-webhook-url'

Get a webhook

 GET /webhooks/{id}

Retrieve a specific webhook resource by its id.

Request example

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

Response

{
"id": "UUID",
"events": [
"newSatelliteImage"
],
"secret": "mRyT257XpFWX",
"name": "Satellite images listener",
"url": "https://agtech.com/leaf/satellite"
}

Get all webhooks

 GET /webhooks

Retrieve all Webhooks.

Request example

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

Response

It returns a list of JSON objects.

[{
"id": "UUID",
"events": [
"newSatelliteImage"
],
"secret": "mRyT257XpFWX",
"name": "Satellite images listener",
"url": "https://agtech.com/leaf/satellite"
}]

Get failed calls for webhooks

 GET /webhooks/failed-calls

Retrieve all failed calls for webhooks.

Request example

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

Response

It returns a list of JSON objects.

{
"items": [
{
"apiOwner": "yourApiOwner",
"createdAt": "2023-04-21T12:16:30Z",
"url": "https://webhook.site/{{uuid}}",
"status": 502,
"response": "<html>\r\n<head><title>502 Bad Gateway</title></head>\r\n<body bgcolor=\"white\">\r\n<center><h1>502 Bad Gateway</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n",
"requestBody": "{\"leafUserId\": \"uuid\", \"fileId\": \"uuid\", \"type\": \"automergedFileProcessingFinished\", \"timestamp\": \"2023-04-21T12:16:27.997586Z\"}"
},
{
"apiOwner": "yourApiOwner",
"createdAt": "2023-04-24T18:35:53Z",
"url": "https://webhook.site/{{uuid}}",
"status": 502,
"response": "<html>\r\n<head><title>502 Bad Gateway</title></head>\r\n<body bgcolor=\"white\">\r\n<center><h1>502 Bad Gateway</h1></center>\r\n<hr><center>nginx</center>\r\n</body>\r\n</html>\r\n",
"requestBody": "{\"leafUserId\": \"uuid\", \"fileId\": \"uuid\", \"type\": \"automergedFileProcessingFinished\", \"timestamp\": \"2023-04-24T18:35:52.187785Z\"}"
},
{
"apiOwner": "yourApiOwner",
"createdAt": "2023-04-24T18:35:53Z",
"url": "https://flamboyant-flower-64651.pktriot.net/",
"requestBody": "{\"source\": \"SYNC\", \"leafUserId\": \"ff044168-45aa-00d8-8b7e-8632d5c23616\", \"fieldId\": \"ed080ca3-69fe-365c-972f-a0d000fe7c0e\", \"type\": \"fieldCreated\", \"timestamp\": \"2023-04-24T18:35:53Z\"}",
"connectionError": "ConnectionError: HTTPSConnectionPool(host='flamboyant-flower-64651.pktriot.net', port=443): Max retries exceeded with url: / (Caused by ProtocolError('Connection aborted.', RemoteDisconnected('Remote end closed connection without response')))"
}
]
}
info

In case of alert delivery failures, Leaf Alerts will make new attempts at 1, 30, 60 and 240 minutes.

Delete a webhook

 DELETE /webhooks/{id}

Delete a specific Webhook resource by its id. Returns 204 status code if the delete succeeded.

Warning

If you delete a Webhook resource, we no longer will send you the events the webhook listens to.

Request example

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

Other channels

ArcGIS

info

This option is a beta feature

The alerts can be delivered in other channels like the arcgis that enables the alert to be sent direct to an ArcGIS Geoprocessing service.

Create an ArcGIS alert

 POST /arcgis

Creates a alert for be consumed in an ArcGIS geoprocessing service specifying which events you want to be notified about and where (server URL). The alert will begin receiving events immediately after it is created.

It's not possible to create different alerts that listen to the same events. For example, if you have already registered a alerts listening for newSatelliteImages and try to register another one, you'll get a 400 response with error eventRegisteredTwice.

Request body

ParameterTypeDescription
eventsenum name of the event typeThey are defined in the "Events" section of the services chapters (e.g. newSatelliteImage)
namestringThe name of your alert
secretstringThe secret used for HMAC authentication. We sign payload with this secret. See more here
urla valid HTTP URL stringThe address of your geoprocessing service, make sure to use this format: https://{ArcGIS Server url}/server/rest/services/{service name}/GPServer/{toolname}/submitJob?f=json

The allowed keys to be filled in events are:

  • credentialsLimitedPermission, credentialsUnauthenticated, fieldCreated, fieldBoundaryCreated, fieldBoundaryUpdated, uploadedFileProcessingFinished, uploadedFileProcessingFailed, providerFileProcessingFinished, providerFileProcessingFailed, mergedFileProcessingFinished, mergedFileProcessingFailed, automergedFileProcessingFinished, automergedFileProcessingFailed, operationCreated, operationUpdated, operationProcessingFinished, newSatelliteImage, machineCreated, machineUpdated, machineDeleted

To see the detailed description of each of these events, click here.

Example in JSON:

{
"events": [
"newSatelliteImage"
],
"name": "Satellite images listener",
"secret": "mRyT257XpFWX",
"url": "arcgis geoprocessing url"
}

Request example

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN' \
-d 'Your paylaod as specified above'
'https://api.withleaf.io/services/alerts/api/alerts/arcgis'

Response

It returns a JSON containing information about the webhook created.

{
"id": "UUID",
"events": [
"newSatelliteImage"
],
"name": "Satellite images listener",
"secret": "mRyT257XpFWX",
"url": "arcgis geoprocessing url"
}

Geoprocessing configuration

This option requires that the geoprocessing is publicly available, that is, without authentication.

To prevent anyone from using your service inappropriately, consider implementing the secret validation mentioned here.