How To Use Production Webhooks

Electric Imp’s impCentral™ provides two event-triggered webhooks which customers can use to notify their own record-keeping systems when Connected Factory and subsequent processes take place. These webhooks are configured on a per-Device Group basis and will not be triggered if they have not first been configured.

The two webhooks are:

• Blessing — This is called when a Device Under Test has been successfully blessed and become a Production Device.
• BlinkUp — This is called when an end-user successfully activates a Production Device using BlinkUp™.

Note Webhooks are available to both Production Device Groups and Test Production Device Groups, and are configured for each of these types separately.

The Blessing Webhook

Usage

The Blessing webhook is triggered automatically when a Device Under Test (DUT) has been successfully blessed, ie. it has become a Production Device that is ready for sale and end-use.

The Data Sent

A Squirrel table containing the keys device_id and imp_id, which are assigned to the values of these device properties. By default, the table is encoded in JSON format (see Webhook Delivery, below).

Notes

The device_id is the unique device ID of the Production Device. You may wish to store this value in a database; it will subsequently be sent by the BlinkUp webhook — if you have configured it for the same (Test) Production Device Group — when an end-user successfully activates the device using BlinkUp.

The imp_id is not the blessed device’s MAC address (supplied by the embedded imp), though it is derived from it.

Example

When your target device is successfully blessed, there will be an HTTP(S) POST to your URL with the following JSON-encoded data:

{ "device_id" : "0123456789abcdef",
  "imp_id"    : "0123456789abcdef" }

The BlinkUp Webhook

Usage

The BlinkUp webhook is triggered automatically upon the successful activation of a Production Device by an end-user.

The Data Sent

A Squirrel table containing the keys device_id, plan_id and token. The first of these is assigned to the value of this device property. The second and third keys are provided by the app managing the BlinkUp process: the plan ID retrieved by the app from the Electric Imp impCloud™ (or re-used after a previous configuration); the enrollment token is issued to the device by the enrollment server by way of your BlinkUp SDK-based app. By default, the table is encoded in JSON format (see Webhook Delivery, below).

Notes

The device_id is the unique device ID and will match the value sent by the Blessing webhook, if it has been configured for use.

The plan_id is used to distinguish one end-user from another. The device ID and the plan ID are used to generate the unique agent URL at which the user-specific instance of the agent software can be contacted. Your mobile app will retrieve a new plan ID from the Electric Imp enrollment server when the end-user first initiates a BlinkUp. This plan ID can be retained and used again should the user re-configure their device using BlinkUp. If you do not do so, a new plan ID to be generated for the user and thus a new agent. Any data preserved by the previous agent, such as device personalization settings, will be lost.

The token is a 16-digit hex number generated by the Electric Imp enrollment server and sent to the BlinkUp SDK-based app when the app initiates the BlinkUp process to configure a Production Device. The token is passed by BlinkUp to the device, which uses the code to identify itself to the impCloud once it has connected to the Internet.

Example

When an end-user configures one of your products using your app and BlinkUp, there will be an HTTP(S) POST to your URL with the following JSON-encoded data:

{ "device_id" : "0123456789abcdef",
  "plan_id"   : "0123456789abcdef",
  "token"     : "0123456789abcdef" }

Webhook Delivery

The webhooks can be delivered to the URL you specify via HTTP(S) POST in one of two formats:

• JSON encoded — The data will be encoded with http.jsonencode() and delivered with the content type "application/json". This is the recommended format and is the default setting.
• URL encoded — The data will be encoded with http.urlencode() and delivered with the content type "application/x-www-form-urlencoded"”. This format is provided primarily for legacy applications.

Webhook Configuration

The two webhooks are configured in impCentral on a per-Production Device Group basis.

• Select the Account you are working on to view its Products list.
• For production testing:
  • Select the Test Zone.
  • Click the Test Production Device Groups sidebar icon ().
  • For the chosen Test Production Device Group, click Settings under MANAGE.
• For production:
  • Select the Production Zone.
  • Click the Production Device Groups sidebar icon ().
  • For the chosen Production Device Group, click Settings under MANAGE.

In each case, the appropriate settings panel will appear, and you can enter or update the webhook settings:

In the URL field, enter the address of the resource which will be processing incoming messages, and select your preferred encoding type (see Webhook Delivery, above). Finally, click the Update Settings button to save the configuration information, or Cancel to leave the webhook unchanged.

Error Handling

The Electric Imp server responsible for calling the webhooks does not determine whether the webhook was successfully received by the target or whether delivery failed. If a webhook is misconfigured or its target resource becomes unavailable, the Electric Imp server will not detect this.

Tutorial

You can find a worked example of using webhooks and factory agents to log data with third-party data collection and logging services here.