# Webhook Integration {% hint style="warning" %} Webhook integration "***Preview***" document {% endhint %} {% hint style="danger" %} **Disclaimer: The schemas (data fields) of webhook messages you receive in your application may be updated at any time without prior notice, but only backwards compatible changes will be made (adding fields, we won't delete fields, nor change the name or type of fields). While we strive to keep this documentation up-to-date, please refer to the**** *****built-in svix documentation (Event Catalog in your Integration Application)***** ****for the latest information.** {% endhint %}
Table of Contents * [What is a Webhook](#what-is-a-webhook) * [How Webhooks Work](#how-webhooks-work) * [Advantages of using Webhooks](#advantages-of-using-webhooks) * [Webhook Configuration](#webhook-configuration) * [Adding an Endpoint](#adding-an-endpoint) * [Viewing Messages](#view-messages) * [Message Attempts](#message-attempts) * [Replay messages](#replay-messages) * [Filtering Event Types/Messages](#filtering-event-types-messages) * [Event Catalog](#event-types) * [Event Types](#event-types) * [alert-event.new](#alert-event.new) * [alert.new](#alert.new) * [wf.measurement.new](#wf.measurement.new) * [Editing an Endpoint](#edit-an-endpoint) * [Editing Subscribed Events](#edit-subscribed-events) * [Testing End Points](#testing-endpoints) * [Disabling an Endpoint](#disabling-an-endpoint) * [Deleting an Endpoint](#deleting-an-endpoint)
*Dryad allows customers to receive sensor data via **webhooks** using the new **Silvanet API integration** feature in the **Silvanet Site Management Application**.* ## What is a Webhook ***Webhooks send messages on specific events in formats like JSON, XML, or form-encoded data to specific HTTP(S) endpoints configured in your application. Silvanet uses JSON as the content type for its webhook messages.*** ## How Webhooks Work A webhook is a service that listens for specific events and sends a message to a designated URL (the endpoint) on your application when those events occur. For example, Dryad can send a webhook every time a fire alert event occurs, which will then be displayed in your application within the Silvanet Site Management Application. The webhook consists of the following entities: * **Messages** - These are the webhooks being sent. A message can have contents and a few other properties. * **Application** - This is where the messages are sent to. You can create one application per organization on your platform. * **Endpoints** - Endpoints are the URLs messages will be sent to. Each application can have multiple endpoints, and each message sent to that application will be delivered to all of them, unless you are not subscribed to specific events for each endpoint. Endpoints listen for webhook messages. * **Event** - When an event occurs, it triggers a webhook message. The following diagram shows how webhooks are sent to your endpoint if a specific event occurs.

Dryad Webhook mechanism for delivering messages

## Advantages of Using Webhooks * Customers can add any number of endpoints to their application (Webhook Portal) and edit them. * Customers can choose which event types are sent to which endpoint. By default, all messages are sent to all endpoints. * Webhooks use stateless HTTP requests to ensure that no persistent connections are required. * Webhooks follow an event-driven model, where a message is triggered only when specific events occur, reducing unnecessary communication. * Webhooks allow replaying past and failed messages. ## Webhook Configuration The **Silvanet API integration** feature in the **Silvanet Site Management Application** allows you to configure webhooks by creating an **application** for each **organization** you have and then adding **endpoints** to each application. With these endpoints, you can subscribe to the event types you want, view messages, and recover/replay past and failed messages. {% hint style="danger" %} Only **Admins** and **Super Admins** are allowed to use the **Silvanet API integration** feature to create applications and configure additional settings. {% endhint %} ## Creating an Integration Application * Log in to the **Silvanet Site Management Application** using your credentials. * On the sidebar, click **API Integration**.
* The **Silvanet API Integration dashboard** appears.
* Click on the **Create Application** button to create a new **integration application**.
* In the **Create a New Integration Application** dialog box, select the organization for which you want to create the application. For example, `Dryad Internal`. {% hint style="info" %} *You can create only one application per organization.* {% endhint %}
* Click on the **Submit** button to create the application.
* The application you created will be listed under **Current API Integrations**.
## Adding an Endpoint To receive messages, you need to add an **endpoint** to the **Application**. Of course, you can add more than one endpoint. * On the **Silvanet API Integration** page, under **Current API Integrations**, click on the **application name** you want to configure. * The application page appears, and the application name can be seen at the top left of the page. * Click **Endpoints** tab if it is not selected by default. * Click on the **Add Endpoint** button. {% hint style="info" %} You can add more than one endpoint for each application. {% endhint %}
On the **New Endpoint** page, configure the following:
* **Endpoint URL** -Enter your endpoint URL here. If you don't have an endpoint, you can click on the option **"Configure an endpoint or test with Svix Play."** This will automatically generate an endpoint and fill the textbox for you. You can also use a service like [webhook.site](https://webhook.site/) to generate a URL for your HTTP endpoint. * **Description** - Enter an optional description here mentioning what the endpoint is used for. * **Subscribe to events -** Select one or more event types that you want to subscribe to by clicking on the checkboxes. If you want to add all the event types of a specific group, just click on the group. {% hint style="info" %} If you don't subscribe to any event types, your endpoint will receive messages for all event types by default. {% endhint %} * **(****Optional****) Advanced Configuration - click to expand this section.** * Select **Endpoint rate limiting (throttling)** checkbox. * **Rate Limit (per second)** - provide the maximum number of webhook messages allowed to send to this endpoint *per second*. For example, enter `10`, if you want to limit it to 10 messages per second. 0 means unlimited.
* Click on the **Create** button. * The endpoint is added to your application. Your page should look something similar to the following:
## Viewing Messages With the **Endpoints** tab selected, scroll down the page until you can see the table view. It shows all the received messages with their **EVENT TYPE**, **MESSAGE ID**, and **TIMESTAMP.**
* From the table, click a message to view its content. You will be switched to the **Logs** tab. The **message content** is simply a JSON object.
### **Message Attempts** There are two types of message attempts, labelled as: * indicates a webhook event that was successful and has sent a webhook message to your application. * indicates a webhook event that failed due to the unavailability or disabling of the endpoint, or because of a server error. ### Replay Messages Use the following options to replay messages to recover past and failed messages: * **Replay all messages** - You can replay the past or failed all the messages using the **replay** button to receive those webhook messages to your application. * **This option is suitable to replay all the messages from some point in the past.** * In the table, use the **TIMESTAMP** to find the message that closest to the desired time. For example, if you want to replay all messages starting from 2:54 PM, locate the message with the nearest timestamp. Click on the three dotted menu of that message and then select **Replay**.
* The following dialog box will appear with three options: * **Resend this message** - select this option to replay the message you selected from the table. * **Resend all failed messages since** - this will replay all the failed messages since the event time of this message. * **Replay all missing messages since** - this will replay all the messages that never attempted for this endpoint since the event type of this message.
### Filtering Event Types / Messages There are several ways you can filter messages. * Filter event types or messages by message attempts using the following buttons: * All * Succeeded * Failed * Using the Filters: Click on the Filters menu to expand it. * **Event Types:** Filter messages by event types by clicking on Filters > Event Type and searching for or selecting the event type(s). * **Tags:** Filter messages by tags. * **After Date / Before Date:** If you know approximately when the message was sent, you can further narrow down the list using the date filter.
## Event Catalog *The **Event Catalog** can be treated as the **built-in svix documentation** for **webhook integration**, which provides **up-to-date information** about **event types**, their **schemas**, and **examples**.* {% hint style="danger" %} **Disclaimer: The schemas (data fields) of webhook messages you receive in your application may be updated at any time without prior notice, but only backwards compatible changes will be made (adding fields, we won't delete fields, nor change the name or type of fields). While we strive to keep this documentation up-to-date, please refer to the**** *****built-in svix documentation (Event Catalog in your Integration Application)***** ****for the latest information.** {% endhint %} Click **Event Catalog** tab. It lists and describes all the **event types** we expose.
### Event Types Click on an **event type** to expand its content. You can see its **schema** and **example JSON payload**.
Currently Dryad exposes three **event types**: ### alert-event.new A new relevant gas scan has been received in the context of an active alert. **Schema:**
**Example:** ```json { "alert": "https://dryad.app/alert-center/63a6a704-5a7a-4d43-9716-10de0d7cc182", "confidence_level": 0.89, "datetime": "2024-04-30T18:10:00.000Z", "device": { "coordinates": { "coordinates": [ 13.404954, 52.520008 ], "type": "Point" }, "eui": "CC1BAA0010000025", "name": "SN 12571" }, "severity": "alert", "urn": "urn:forestfloor:alert-event:84382a41-f97f-441a-bb13-e141b2c4779b" } ``` ### alert.new A new fire alert has been triggered. **Schema:**
**Example:** ```json { "datetime": "2024-04-30T18:10:00.000Z", "site": { "name": "If Berlin was a Forest", "url": "https://dryad.app/sites/999", "urn": "urn:forestfloor:site:baee084d-f6cf-45b0-8227-ac7bdad6ed49" }, "url": "https://dryad.app/alert-center/63a6a704-5a7a-4d43-9716-10de0d7cc182", "urn": "urn:forestfloor:alert:63a6a704-5a7a-4d43-9716-10de0d7cc182" } ``` ### wf.measurement.new Wildfire sensor environmental measurement received. **Schema:**
**Example:** ```json { "air_pressure": 102331, "air_quality": 145, "datetime": "2024-04-30T18:10:00.000Z", "device": { "coordinates": { "coordinates": [ 13.404954, 52.520008 ], "type": "Point" }, "eui": "CC1BAA0010000025", "name": "SN 12571" }, "energy_level": 0.67, "humidity": 57, "site": { "name": "If Berlin was a Forest", "url": "https://dryad.app/sites/999", "urn": "urn:forestfloor:site:baee084d-f6cf-45b0-8227-ac7bdad6ed49" }, "temperature": 18.4 } ``` ## Editing an Endpoint Follow the steps below if you want to update the endpoint URL. * Navigate to your application and select the **Endpoints** tab if it is not selected by default. Then select the **Endpoint** you want to edit under the Endpoints. This will expand the Endpoint configuration section.
* Click on the **Edit** button next to the existing endpoint URL.
* Replace the **existing endpoint URL** with the **new endpoint URL**. * Click on the **Save** button.
## Editing Subscribed Events With your application, you can edit your subscribed events on each endpoint at any time. * Navigate to your application and select the **Endpoints** tab if it is not selected by default. Then select the **Endpoint** you want to edit the subscribed events. This will expand the Endpoint configuration section. * In the right-side panel, under the **Subscribed Events** section, you can see which events you are subscribed to for this endpoint. * Click the **Edit** button.
* Select or deselect the **event types** you want to **subscribe to** or **unsubscribe from**. * Click the **Save** button.
## Testing Endpoints This feature allows you to test your endpoint to see if it will receive messages. Navigate to your application and select the **Endpoints** tab if it is not selected by default. Then select the **Endpoint** you want to test. This will expand the Endpoint configuration section. * Go to the **Testing** tab. * Select an **event type** from the dropdown you want to test.
* Once you select an event type, its schema will display on the page along with an example JSON payload so you can see what fields will be sent with the message. * Click **Send Example** button to send the message.
After sending a message for an event, if successful, you will be able to see it on the **Overview** tab. ## Disabling an Endpoint Navigate to your application and select the **Endpoints** tab, if it is not selected by default. Then select the **Endpoint** you want to disable. This will expand the Endpoint configuration section. Disabling an endpoint will stop messages from being sent to that endpoint. * In the top-right menu, click **Disable Endpoint**.
* Once disabled, a label named `Disabled` will appear on the endpoint page, as shown below.
To enable the endpoint again, click **Enable Endpoint** from the same menu. ## Deleting an Endpoint Navigate to your application and select the **Endpoints** tab, if it is not selected by default. Then select the **Endpoint** you want to delete. This will expand the Endpoint configuration section. On the top-right menu, click **Delete**. This will permanently delete the endpoint from your application and cannot be undone.