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
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 recommented 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

Example in JSON:

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

Sample code

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'

Get a webhook

 GET /webhooks/{id}

Retrieve a specific webhook resource by its id.

Sample code

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

Get all webhooks

 GET /webhooks

Retrieve all Webhooks.

Sample code

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

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.

Sample code

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