Webhook access

External systems and individual IoT devices (hereafter collectively called "devices") can send condition reports to the withthegrid application. Devices identify themselves with a client certificate or a token. This documentation is about access with a token. Devices with a token can interact with the platform by sending:

• HTTPS requests to a URL that starts with https://api.withthegrid.com/iot (Lets Encrypt signed root CA, expires every couple of months)
• CoAP (over DTLS) request to api.withthegrid.com:5684

As developer, you can create a token in your connectivity environment under "Device authentication", "Webhook access". The URL containing the token as shown in the application can be modified as long as it still adheres to the requirements above and the token is present:

• in the HTTP query string under the key t
• OR in the HTTP header x-wtg-token
• OR in the CoAP option 2050

The withthegrid server inspects the incoming request and tries to look up the token. If that is found, the identifier function belonging to that token is run, with the incoming request as parameter. The identifier function is then expected to return the device type hashId and a identifier that uniquely identifies the device among all devices in the connectivity environment.

The identifier function should:

• be written in Typescript,
• be named handle
• have the following signature: handle(args: Arguments): Result

When the identifier function throws an error or when the return is conform the signature, the request will be rejected with a 502 status code.

When the device type is not known by the application, the request will be rejected with a 404 status code. Otherwise:

• when the device identifier does not yet exist, a new device is created and the event handler of the specified device type is run to process the request
• when the device identifier does exist and the device matches the device type, the event handler of the specified device type is run to process the request
• when the device identifier does exist and the device does not match the provided device type, the request will be rejected with a 502 status code.

Example

/**
 * This identifier assumes that the device presents its identifier in the x-mcu-id
 * header and determines its own device type through the x-device-type-hash-id header
 */

function handle(args: Arguments): Result {
  const deviceIdentifier = args.request.headers['x-mcu-id'];
  if (typeof deviceIdentifier !== 'string') {
    throw new Error('x-mcu-id header is not available');
  }

  const deviceTypeHashId = args.request.headers['x-device-type-hash-id'];
  if (typeof deviceTypeHashId !== 'string') {
    throw new Error('x-device-type-hash-id header is not available');
  }

  return {
    deviceTypeHashId,
    deviceIdentifier,
  };
}
Copy

Inspecting activity

You can inspect activity on this identifier function by going to "Activity" in the connectivity environment and filtering "Type" on "Handle incoming request" and "Webhook" on the name given to the webhook.