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:

Description	Endpoints
Create a webhook	POST /webhooks
Get a webhook	GET /webhooks/{id}
Get all webhooks	GET /webhooks
Get failed calls for webhooks	GET /webhooks/failed-calls
Delete a webhook	DELETE /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

Parameter	Type	Description
events	enum name of the event type	They are defined in the "Events" section of the services chapters (e.g. newSatelliteImage)
name	string	The name of your webhook
secret	string	The secret used for HMAC authentication. We sign payload with this secret. See more here
url	a valid HTTP URL string	The address of your webhook server

Example in JSON:

{

"events": [

"newSatelliteImage"

],

"name": "Satellite images listener",

"secret": "mRyT257XpFWX",

"url": "https://yourwebhook.com/leaf/satellite"

}

Request example

• cURL
• Python
• JavaScript

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
• Python
• JavaScript

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
• Python
• JavaScript

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
• Python
• JavaScript

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
• Python
• JavaScript

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')))"

}

]

}

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
• Python
• JavaScript

curl -X DELETE \

-H 'Authorization: Bearer YOUR_TOKEN' \

'https://api.withleaf.io/services/alerts/api/alerts/webhooks/{id}'