How to apply a Public Key on a WebHook endpoint

When we create an Automation or cloud-connected device on the SmartThings Developer Workspace of the WebHook endpoint type, a Public Key is generated for us. We need this Public Key so that our WebHook endpoint can verify requests from SmartThings.

Public Key

To better understand how we should use this Public Key, see at the below diagram depicting WebHook endpoint interactions with SmartThings.

SmartThings WebHook

From the diagram, we can follow this sequence:

  1. First, we start our WebHook service hosted either on an external server machine or on our own local machine (making use of ngrok to tunnel it to the internet).
  2. We then create an Automation or cloud-connected device on Developer Workspace. We set the SmartApp type as WebHook endpoint and input our WebHook target URL.
  3. After we click the SAVE AND NEXT button, Developer Workspace (via SmartThings) will call a PING callback on our just-registered WebHook service.
  4. Our WebHook service should return a valid PING response.
  5. Upon receiving the valid PING response, Developer Workspace will issue our Public Key. We then copy/save this Public Key.
  6. We stop our WebHook service.
  7. We integrate the Public Key into our WebHook service. Refer to the example code on HTTP signature verification.
  8. We start the WebHook service again, now ready to receive further callbacks (see SmartApps lifecycle for a complete list of callbacks) from SmartThings with Public Key validation active.

Steps 6 to 8 are particularly important. If we forget to restart the service when integrating the Public Key into the WebHook script, the Public Key will not be used to validate requests, and this will cause errors on further callbacks called from SmartThings.

Now that you know how to use a Public Key, you may want to try the Automation SmartApp sample in our Automation guide.