Webhook & Open API now in Beta!

App Beta Testing
,
#1

If you're a part of our beta program, you should now have the API integration feature in your "Add device" menu!

IMG_0920
IMG_09207383×2532 1.02 MB

Open API

Once enabled, the Open API will give you access to a token which can be used to authenticate HTTPS calls made to documented endpoints.

You can use the token in your authorization header as:

AUTHORIZATION: Bearer {TOKEN}

Our base URL is: http://app.equiwatt.com/

We’re currently only making available one endpoint which is /equivents. This will give you data on if an equivent is currently live, and some data on past equivents too. See more docs

The endpoint is rate limited at 1 call/second and 10 calls/minute.

Let us know what other endpoints you might find useful, and we can work on enabling them! We will also work on some better documentation when we bring this out of beta.

Webhook

Another part of our API Integrations feature is the Webhook, the webhook triggers allow you to enter a URL, and have us call that URL when the trigger condition is met (equivent started or ended for now).

After you’ve saved a URL, you can test if your URL works by sending a demo trigger.

You could use this with Home Assistant as described here or with any other custom integrations you could think of!

Let us know what other webhook triggers you’d like to see!

Please note that currently, you will still need to indicate your manual participation during an equivent in-order to receive points via your Smart Meter. This will change once the API Integrations feature comes out of beta.


Happy testing & automating! 🎉

#2

Many thanks @mahen - this looks good, I’ve integrated against the open API and receiving events data no probs (after a bit of fiddling to get bearer auth working at my end). This will allow me to automate shutdown of other devices during an equivent, so is going to be very useful.

1 Like
#3

Hi @mahen , first observation is that current_event is not populated when an Equivent is running - instead the first previous event has the start time populated with today’s date/time, and end_time null (see log info below). I guess the current_event should be populated with those values as well? Thanks

I, [2022-12-09T16:12:52.536643 #28347] INFO – : Updated Equi: {“success”:true,“msg”:null,“data”:{“current_event”:null,“previous_events”:[{“start_time”:1670601661,“end_time”:null},{“start_time”:1670403676,“end_time”:1670407262},{“start_time”:1669744866,“end_time”:1669748462},{“start_time”:1669402864,“end_time”:1669406462},{“start_time”:1668792669,“end_time”:1668796262},{“start_time”:1668711667,“end_time”:1668715262},{“start_time”:1668531667,“end_time”:1668535262},{“start_time”:1668193334,“end_time”:1668196863},{“start_time”:1667934067,“end_time”:1667937662},{“start_time”:1667590266,“end_time”:1667593862}]}}

1 Like
#4

Thank you! Yes, the “current_event” should have the current event’s “start_time” instead of it being in the previous events. Will have a look at why it isn’t showing up this way for you, definitely buggy there.

#5

Thanks @mahen - as a workaround I’ve coded to use previous_events.end_time = null to trigger the equivent “on” logic, so no problem to wait for the bug fix.

1 Like
#6

Hello, this should now be fixed as we have pushed a new update. Do let me know if you have further complications!

#7

Hi Elizabeth!

Would you mind sharing what fiddling you did to get the bearer auth working please?

I’m struggling to get the Home Assistant RESTful sensor to successfully present my token, so I’m wondering if I’m falling afoul of the same issue?

Thanks!

#8

Of course - I’m using Ruby on PI4 (rather than HA), but hopefully can be of help.

I’ve included my ruby class below that hits the Equiwatt REST api, if that helps; I pass it the api key on creation, and then call update on it to hit the api (which builds the URL, adds key to header, and then stores results in a json). The other REST apis I use have Basic auth, rather than Bearer, so the changes I had to make were to impement Bearer auth.

In your case I would check that you are hitting the right URL (https://app.equiwatt.com/api/v3/equivents/), and that you are passing the actual word Bearer in the header (at front of the key field) as that is what tripped me up.

Google found me this page on HA REST api sensors:

About half way down is the useful bit:

If you are accessing a resource protected by a Bearer token in an Authorization header, you can either put the token in the header field of the sensor configuration (not recommended) or store the token in your secrets.yaml file. In that case, be sure to include the word Bearer in the secrets file.

sensor:
  - platform: rest
    resource: http://IP_ADDRESS:5000/sensor
    headers:
      Authorization: !secret my_sensor_secret_token

YAML

Copy

Example entry for the secrets.yaml file:

my_sensor_secret_token: Bearer gh_DHQIXKVf6Pr4H8Yqz8uhApk

I’d recommend trying it first with the key in your config header (ie the not recommended option!!), with and without Bearer at the front. Then once working move it off in to the secrets file (where it states nice and clearly that Bearer is needed at the front).

Good luck!

My ruby class:

frozen_string_literal: true

require ‘pathname’
require ‘net/http’
require ‘uri’
require ‘json’
require ‘time’

Equiwatt data integration.

class Equilib
def initialize(api_key:)
@api_key = api_key

end

def update
response = http.request(request)

if response.is_a?(Net::HTTPOK)
  body = response.body
  # test that we have sane looking JSON before we save it
  @data = JSON.parse(body)

  data_file.write(body)
  LOGGER.info "Updated Equi: #{body}"

else
  LOGGER.fatal "Error updating Equi: #{response}"
end

end

private

def data
@data ||= JSON.parse(data_file.read)
rescue Errno::ENOENT, JSON::ParserError
nil
end

def data_file
@data_file ||= Pathname.new(‘equi.json’)
end

def url
@url ||= URI.parse(“https://app.equiwatt.com/api/v3/equivents/”)
end

def http
@http ||= Net::HTTP.new(url.host, url.port).tap do |http|
http.use_ssl = true
end
end

def request
#build key
bearer_api_key = 'Bearer ’ + @api_key

@request = Net::HTTP::Get.new(url.request_uri, {'Authorization' => bearer_api_key})

end

end

2 Likes