Leaf Alerts allow developers to trigger actions based on Alert events instead of constantly checking to see if new data is available across different sources. This enables a better user experience and easier, more efficient programming.
Why Alerts Matter
Most data providers expect applications to continuously check to see if new data is available. This introduces challenges for both developers and users as they must set rules of how often to check for new data, manage expectations of timing between data upload and when it will appear in their applications, and maintain their recurring queries.
Leaf Alerts allow developers to subscribe to events from all data providers in one consistent format so they can immediately serve new data to their customers without needing to continuously query for new data. This is especially useful since most data providers do not natively support webhooks.
How It Works
Leaf Alerts instantly send an event to a user’s webhook when new data or updated data (such as field boundaries, machine operation files, authorization credentials, and more) is available from any third-party system.
Examples of Alert Types:
- fieldCreated
- uploadedFileProcessingFinished
- uploadedFileProcessingFailed
- newOperation
A full list of Alert types can be found here.
Benefits of Leaf Alerts:
- Compatible with all providers connected with Leaf.
- Leaf has created the functionality even when the majority of providers don’t natively support Alerts.
- Trigger workflows.
- For example: if a user updates a field boundary in Climate Fieldview™, you can receive an alert and trigger a prompt in your application to ask if the user wants to update the boundary to the new geometry in your application as well.
- Easier and more efficient programming.
- Developers can use alerts to trigger workflows in a consistent way across all providers.
Guide to Using Alerts
Following is a short guide on how to sign up for the alerts service.
Requirements:
- Have an endpoint open to POST requests (webhook via TLS)
- Have an account registered with Leaf
Registering a Webhook
The webhook endpoint is code on your server, which could be written in Ruby, PHP, Node.js, etc. The webhook endpoint has an associated URL (e.g., https://example.com/webhooks). Leaf will send notifications to this endpoint which are Event objects. These Event objects contain all the relevant information about what happened, including the type of event and the data associated with that event.
To begin, you must configure your Leaf account with your webhook URL and specify which notification events to send. To do this, make a POST request to:
The request body has the following format:
- url: your webhook URL
- secret: a secret used for HMAC authentication. We’ll sign all request bodies with this secret as the HMAC key, so you can verify the signature and ensure that requests came from us
- name (optional): a name for the webhook being registered
- events: this array specifies the name of the events that the webhook should be alerted about. See the section “Events” below for details.
When receiving that request to register a webhook, our backend tries to confirm the communication with your webhook, sending a request like the following:
If the response status code is a successful status code (>= 200 and 300), then the webhook will be registered, otherwise we respond 400 BAD REQUEST with “errorKey” non2xxSuccessfulStatusCode.
The identifier of the newly created resource will be present in the “location” header field of the response.
You can register multiple webhooks, but if an event type is already registered to one, it shall not be added to another.
Events
The alerts for any type of event will always have the following two properties:
In addition to those, each event can have its own properties.
fieldCreated
Happens when a field is created, for example when one creates a field. This works as a sample event for you to experiment how webhooks work. You can force an event to happen by requesting the creation of a field, and check if the webhook you registered correctly receives the alert.
The alert has the following form:
uploadedFileProcessingFinished
Happens when all steps of the processing of an operations file that was uploaded to Leaf are finished, producing all the resources (standard GeoJSON, PNG properties, PNG of the zip file, summary).
The alert has the following form:
uploadedFileProcessingFailed
Happens when the processing of an operations file that was uploaded to Leaf is not completed, that is, when it fails in some of the steps (generation of: standard GeoJSON, PNG properties, PNG of the zip file, summary).
The alert has the following form:
Authentication
It’s very important to confirm that requests received on your webhook are sent from Leaf, to avoid IP spoofing attacks. To that end, you should verify webhook signatures.
Leaf generates signatures using a hash-based message authentication code (HMAC) with SHA-256. The signed content has no line breaks, it's a string of the raw JSON with white-spaces after “:” and “,”.
The digest is added to the X-Leaf-Signature header encoded in base 64.
Here is an example on how to verify the request in your webhook using Python:
Get Started!
Visit Leaf's documentation to learn more about Leaf's Alert service.