The SolarUser Event Hook API provides methods to manage execution of pre-defined services in response to events generated by SolarNetwork. Conceptually these hooks are like push notifications sent from SolarNetwork to your own applications.

Events define what data is available to be used by hooks. Events all include a topic property that defines a unique category for the event. This category determines the type of event and what other properties will be available.

SolarNetwork does not make any guarantees as to when a hook service will be invoked after a given event has been generated, other than "eventually". In practice hooks will be invoked as quickly as possible, but you should not make any assumptions about their timing.

SolarNetwork does not make any guarantees on the order or concurrency of invoked hook services. Put another way, the hooks can be invoked in parallel and out of order with respect to the creation date of the events.

Any application making use of SolarNetwork events should keep these considerations in mind, and make sure its handling of the hook events is flexible enough to accomodate them.

Aggregate Updated datum events are generated after SolarNetwork has computed an aggregate value for a specific node and source. Keep in mind that SolarNetwork might compute an aggregate datum many times, and thus post Aggregate Updated events with identical content many times. For example, if a node posts datum for a source every minute then over the course of a single hour SolarNetwork might recompute a single datum source's hourly aggregate datum many times because the hourly aggregate value is impacted by the changing raw source data.

SolarNetwork does not make any guarantees as to when it computes aggregate datum values, other than "eventually".

The aggregationKey property will be one of the following supported aggregation types:

An example Aggregate Updated node source event, expressed as JSON, looks like this:

{
  "topic"          : "datum/agg/update",
  "userId"         : 123,
  "hookId"         : 234,
  "nodeId"         : 456,
  "sourceId"       : "/power/1",
  "aggregationKey" : "M",
  "timestamp"      : 1590926400000
}

The following hook services are available on SolarNetwork.

The SQS hook service publishes events as JSON objects to an AWS SQS queue. The queue must exist already for SolarNetwork to be able to publish events to it. The service supports the following settings:

⚠️ NOTE: the secretKey property is a secure setting and will be shown in API results as a digest value. When posting values you can omit this property to leave the value unchanged.

Here's an example serviceProperties object for the SQS hook service that could be used when posting a hook configuration:

{
  "region"    : "us-west-2",
  "queueName" : "node-event-dest-test",
  "accessKey" : "AAAAAAA555555555FFFF",
  "secretKey" : "super.secret.key.here"
}

All dates and times are represented in the Gregorian calendar system. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens. Some endpoints return localized messages. See the localized setting specifiers section for more information.

Lists the available node-related hook services.

The response will be a list of localized event hook service objects. The objects have the following properties:

An example response looks like this:

{
  "success": true,
  "data": [
    {
      "id": "net.solarnetwork.central.user.event.dest.sqs.SqsUserNodeEventHookService",
      "locale": "en",
      "localizedName": "AWS Simple Queue Service (SQS) Node Event Hook Service",
      "localizedDescription": "Publish node events to an AWS SQS queue as JSON-formatted message objects.",
      "settingSpecifiers": [
        {
          "key": "region",
          "defaultValue": "",
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "queueName",
          "defaultValue": "",
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "accessKey",
          "defaultValue": "",
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "secretKey",
          "defaultValue": "",
          "secureTextEntry": true,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        }
      ],
      "localizedInfoMessages": {
        "region.key": "Region",
        "region.desc": "The SQS queue region to use. For example <code>us-west-2</code>.",
        "queueName.key": "Queue Name",
        "queueName.desc": "The SQS queue name to use. This queue must exist already.",
        "accessKey.key": "Access Key",
        "accessKey.desc": "The AWS access key to use for posting the event data.",
        "secretKey.key": "Secret Key",
        "secretKey.desc": "The AWS secret key to use for posting the event data."
      }
    }
  ]
}

Lists the available node-related hook configurations.

The response will be a list of event hook objects. See Node hook view response for details.

Create or update a node-related hook configuration. To create a configuration omit the id property in the posted data. To update a configuration include the id property for the configuration you want to update. When updating, the provided object completely replaces the existing configuration so be sure to submit a complete configuration object.

The response will be a the complete configuration object, including the unique id generated when creating the object. See Node hook view response for details.

View a specific node hook configuration object.

The response will be a node event hook object. The object will have the following properties:

An example response looks like this:

{
  "success": true,
  "data": {
    "id": 1,
    "userId": 123,
    "created": "2020-06-16 03:04:04.82932Z",
    "name": "SQS Test",
    "topic": "datum/agg/update",
    "nodeIds": [
      234
    ],
    "sourceIds": [
      "/power/1"
    ],
    "serviceIdentifier": "net.solarnetwork.central.user.event.dest.sqs.SqsUserNodeEventHookService",
    "serviceProperties": {
      "region": "us-west-2",
      "accessKey": "AAAAAAA555555555FFFF",
      "queueName": "node-event-dest-test",
      "secretKey": "{SSHA-256}YRDfTtemkw5iMXETEjZVE4ANcQUJ/BDqDfUqbyiRGrZYvsWt+azABg=="
    }
  }
}

Delete a specific node hook configuration object.

Lists the available node-related event topics that can be configured on event hooks.

The response will be a list of localized event topic descriptor objects. The objects have the following properties:

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": "datum/agg/update",
      "locale": "en",
      "localizedName": "Aggregate Updated",
      "localizedDescription": "Event triggered when SolarNetwork updates an aggregate value for a node source. The event message includes <code>timestamp</code> and <code>aggregationKey</code> properties that reveal which aggregate datum was affected."
    }
  ]
}