A webhook is a URL on your DS client to which Evercloud can send event notifications, associated with a callback function that handles the data included in a notification.

There are currently three event types:

The gateway_status event is triggered each time a gateway sends a status update to Evercloud. Gateways send a status summary approximately every five minutes and a detailed status message once per day.
The sensor_reading event is triggered each time a sensor sends a reading to Evercloud through an Evergateway. Sensors are typically set to send a reading once a minute.
The threshold_crossed event is triggered when a reading passes a user-defined threshold value. This event type currently under construction.

Every webhook subscribed to the gateway_status event type receives a gateways_status notification of every gateway status message that Evercloud receives from any gateway associated with your account. Each notification contains a single gateway status message. Status messages can use one of three schemas, a v1 status message, a v3 status message or a daily status message. For details of the gateway status messages see Evergateways

Every webhook subscribed to the sensor_reading event type receives a sensor_reading notification of every sensor reading that Evercloud receives from your installation. Each event notifications contains a single reading from a specific Eversensor. Readings include both type-independent information about the sensor itself, and either temperature/humidity or vibration/electrical data about the monitored equipment. For details of the sensor-reading schema, see Eversensors API overview.

The callback that you associate with a webhook handles the sensor-reading or gateway-status data, typically by storing it in a time-series database, or passing it to another tool for analysis or display. It is the client's responsibility to identify the message schema type, and filter the data for properties of interest.

Resource summary

The Webhooks API lets you create webhooks, retrieve and modify existing webhooks, and delete webhooks that are no longer needed.

Base URI is https://api.data.everactive.com/ds/{ds-api-version}

Webhooks endpoints	Supported operations
`{baseURI}/webhooks`	POST creates and configures a new webhook subscription. GET retrieves a list of currently subscribed webhooks.
`{baseURI}/webhook/{webhookId}`	GET retrieves the configuration of a specific webhook. PUT updates the configuration of a specific webhook. DELETE removes a specific webhook from the database.

Creating webhooks

A POST request {baseURI}/webhooks creates and configures a new webhook-subscription object. The body of the request contains a JSON object that configures the new webhook.

Body parameters
`callbackUrl`	Required. The callback URL to which Evercloud will post sensor readings. Must use HTTPS. The callback function receives a single argument, a JSON object containing one sensor reading. For details of the sensor-reading schema, see Eversensors API overview.
`eventType`	Required. The event type that this webhook handles, one of `gateway_status` or `sensor_reading`. The `threshold_crossed` type is not yet available.
`enabled`	True to enable this webhook, false to disable it.
`headers`	An array of additional headers (key-value pairs) to forward with every HTTPS request. Headers are case-insensitive and no duplicate headers are allowed.

Response

On success, the body of the response contains a JSON object that includes the unique identifier assigned to the new webhook. Use this value as a path parameter to address the individual webhook.

Retrieving webhooks

A GET request {baseURI}/webhooks retrieves a list of all currently subscribed webhooks. You can get paged results for large lists.

Query parameters	Description
`page` `page-size` `sort-by` `sort-dir`	Get paged and sorted results.

Response

On success, the body of the response contains a JSON object with an entry for each defined webhook, with its unique ID, URL, the event type handled, and enabled status,

Managing webhooks

Use the assigned webhook UID as a path parameter to examine and update the configuration of an existing webhook, or remove a webhook that is no longer needed from the database.

Examine webhook configuration

A GET request to {baseURI}/webhook/{webhookId} returns the current configuration.

Path parameter	Description
`webhookId`	The unique identifier of the webhook object, as assigned on creation.

Response

On success, the body of the response contains a JSON object that includes the URL, the event type handled, and the enabled status of this webhook, and the HTTPS headers currently sent with all notifications.

Update webhook configuration

A PUT request to {baseURI}/webhook/{webhookId} updates the configuration of an existing webhook.

Path parameter	Description
`webhookId`	The unique identifier of the webhook object, as assigned on creation.

You can use this call to disable a currently used webhook temporarily, and to re-enable it later.

Query parameters
`callbackUrl`	The callback URL that Evercloud will post sensor readings to. Must use HTTPS.
`eventType`	The event type that this webhook handles, one of `gateway_status` or `sensor_reading`.
`enabled`	True to enable this webhook, false to disable it.
`headers`	An array of additional headers to forward with every HTTPS request. Headers are case-insensitive and no duplicate headers are allowed.

Delete a webhook

A DELETE request to {baseURI}/webhook/{webhookId} permanently removes this webhook from the database.

Path parameter	Description
`webhookId`	The unique identifier of the webhook object, as assigned on creation.