Getting Started with Webhooks

What are webhooks and how does Yonomi use them?#

Webhooks - also known as user-defined HTTP callbacks - are automated, one-way messages sent from a service to a client when an event occurs. Webhooks are a scalable, efficient and convenient way for applications to receive real-time information of the events monitored or managed by that service.

Yonomi uses webhooks to asynchronously provide data about device state changes to your applications. Here are a few example uses for Yonomi webhooks:

• Notify a user when a thermostat has sensed an unoccupied space has reached a target temperature

• Collect and store motion events from a motion sensor in an external data repository so they can be graphed and presented for analysis

• Notify a property manager when a smart lock’s remaining battery life has dropped below a designated percentage.

All of these state changes are represent by different events, and webhooks provide a mechanism for applications to receive notifications about those events so they can be used to build meaningful IoT solutions.

📘 For a full list of all event types supported by the Yonomi platform visit the Yonomi Webhooks reference.

New to Webhooks?#

​ If you’ve never used webhooks, it’s a good idea to review some beginning content on the topic. While webhook tutorial coverage is outside the intended scope of this guide, below are links to a few tutorials covering the topic:

• Pipedream - a low code API integration platform for developers - offers a good online guide, Webhooks - The Definitive Guide, which covers substantial ground for beginners.

• FreeCodeCamp - If you prefer a video tutorial, FreeCodeCamp has a Webhook for Beginners video tutorial that does a good job of walking through the basics and getting you up to speed on webhooks.

Working with Yonomi Webhooks#

🚧 Prerequisite: The next few steps require availability of an existing, Yonomi-connected device

Before working with Yonomi Webhooks you’ll need an account and device set up and connected to Yonomi. If you’ve not gotten this far, please review our Getting Started guide - which walks through the set up process - then return here.

If you’re able to run basic information queries and have at least one device associated with a test user account in GraphQL Playground then you’re ready to begin.

We’ll follow 3 basic steps to achieve our webhook integration.

1. Create a webhook endpoint
2. Register and Validate your endpoint
3. Enable your Endpoint (Yonomi task)
4. Execute device actions and observe messages

Create a Webhook Endpoint#

In order to begin receiving webhook messages and HTTP endpoint needs to exist, so creating a webhook endpoint is the first step in working with Yonomi webhooks.

If you already have an endpoint available you can skip to the next section of this guide.

If you don’t have an endpoint, you can set one up using Pipedream. Pipedream is a serverless platform that allows developers to connect APIs together, including webhook-based APIs and is useful for test purposes here. Below are the steps to create a webhook endpoint with Pipedream.

1. Browse to Pipedream and click the Sign Up button to create an account. Once logged in you’ll be directed to your Pipedream Workflow dashboard. In Pipedream, workflows are automated tasks triggered on HTTP requests, schedules, app events or other triggers. We’ll create a workflow to process Yonomi Webhook messages.

2. Click the New + button to create a new pipedream workflow

After clicking the button you’ll see a number of options for triggers on the right side of the screen, including an HTTP / Webhook trigger, which is what we’ll be creating to process Yonomi webhook messages.

3. Click on the HTTP / Webhook trigger.

4. Select the New Requests option to indicate you’ll be processing entire HTTP messages, including header, query parameters and body. This will be required to process messages from Yonomi. (Note: DO NOT select New Requests (Payloads Only), as this would only allow you to process the body/payload of inbound messages, which would not achieve integration with Yonomi).

5. Next you’ll be presented with a screen to configure the message source. Just keep the default values here and click the Create Source button at the bottom of the screen.

6. Your endpoint is now created. You’ll be presented with a screen that shows you the status of your endpoint, along with the endpoint URL. Note that Pipedream endpoints are disabled (Off) by default, as indicated by the toggle control in the top right of the screen.

Click the toggle to change the workflow state from Off to Listening for new events.

Once enabled, the endpoint is ready to start receiving Yonomi webhook messages.

Provide webhook URL to Yonomi Customer Success#

Now that you’ve created and enabled an HTTP endpoint you’ll need to send the endpoint URL to Yonomi for configuration with your Yonomi Platform Tenant. Copy your endpoint URL and send to your Yonomi Customer Success engineer via the Yonomi support portal, email or Slack (if used). If you have more than one tenant/environment, please indicate which environment the URL should be configured against.

By default, Yonomi will configure your endpoint URL to receive all messages generated by your tenant. If you have a preference for a reduced set of messages or only specific messages, please let your Customer Success engineer know which messages should be included for receipt. You’ll find a full list of available events here.

Webhook Validation#

Once Yonomi has received your endpoint URL the webhook will be configured against your Yonomi Platform tenant. Upon configuration, the endpoint will receive its first message. This is an important message to look out for because it contains information that will be used to complete webhook validation. Webhook validation informs Yonomi that your endpoint is active and successfully receiving messages, and a required step to complete before the endpoint receive any future messages.

🚧 Not receiving messages? Make sure you’ve completed the webhook validation process

Webhook validation must be completed before you’ll begin receiving device events from Yonomi. If the webhook endpoint is not receiving messages there’s a chance the webhook validation process was not successfully completed. If you no longer see a validation message on your endpoint or never received one, ensure your endpoint URL is active/enabled and contact Yonomi to have your validation message resent.

An example validation message is shown in the Pipedream dasbhoard image below.

If you’re using Pipedream for capturing and working with webhook events, you’ll find a list of received messages on the left side of the Pipedream dashboard for your HTTP workflow. The very first (and only) message received upon configuration by Yonomi will be the validation message. Clicking on this message will open the contents of the message in the right window as a tree/node list. From here, clicking on the steps.trigger.event node will display the body section of the message, which contains the value needed to complete the validation step.

1. Open the validation message received by Yonomi and identify the values for the validateAt and validationToken variables in the message body.

2. Open up a shell/terminal window and paste the following cURL request into the terminal, replacing {validateAt} and {validationToken} with the values from the message above:

curl --location --request POST {validateAt} \
--header 'Content-Type: text/plain' \
--data-raw '{
    "token": "{validationToken}"
}'

3. Execute the cURL command. If successful, you should receive a response of valid: true. Your webhook endpoint is now validated.

Webhook Enablement#

Upon validation, contact your Yonomi Customer Success engineer once again to inform them you’ve completed the validation step. Your CS engineer will configure and enable your tenant to begin sending webhook messages to your endpoint. This is also a required step; your endpoint will not receive messages until both validated and enabled.

Execute Device Actions and Observe Messages#

Now that the webhook is fully configured, validated and enabled against your webhook endpoint URL, you can do some testing with device actions to see events that come into your endpoint.

Test your integration by Using the GraphQL Playground to perform commands against your device. The image below shows the message sent resulting from an unlock action being performed against a lock.

The image shows deviceEventSetState which provides information about when device state was changed, state values of the device including isLocked, "value": false as well as the trait that this is affecting - in this case the Lock trait. We can also see that this action caused three other events to be registered, another deviceEventSetState, a deviceEventQueueAction and a deviceEventUpdateAction.

If you’ve gotten this far, congratulations! You’ve successfully completed the Webhook Getting Started guide.