Webhooks

Integrate with webhooks so your application can receive updates about connected devices and accounts in near-real time, without having to constantly query our API.

To enable webhook events, you need to register webhook endpoints. After you register them, Enode can push near real-time notifications to your application’s webhook endpoint when events happen in your Enode account. Enode uses HTTPS to send webhook events to your endpoint as a JSON payload that includes up to 100 event objects.

Receiving webhook events is particularly useful for listening to asynchronous events such as when a vehicle has been plugged in, when a solar inverter has started producing, or when a thermostat temperature has changed. Webhooks are triggered whenever there is a change in the state of an asset, ensuring you receive timely updates. If there is no change in the asset's state, no webhook will be sent.

We will periodically send heartbeat events to your webhooks to ensure a continuous and reliable connection to Enode. These heartbeat events check the availability of your webhook and inform you how many events are queued for delivery. This helps you verify that your webhook integration is functioning correctly. Keep in mind that the number of queued events is an estimate and will typically be zero under normal operations.

Copy linkGet Started

To start receiving webhook events, create and register a webhook subscription using the Create WebhookAPI endpoint.

After registering a new webhook subscription, use the Test WebhookAPI endpoint to receive a test event. You can always use the Update WebhookAPI endpoint to make any changes to your existing webhook subscriptions.

Copy linkImplementing your webhook endpoint

Your webhook endpoint should expect to receive POST requests bearing the following case insensitive headers:

And an application/json body containing an array of Events, with the following schema:

[
  {
    "event": "user:vehicle:updated", // String - name of the event
    "createdAt": "2020-04-07T17:04:26Z", // UTC ISO 8601 - time at which the event was triggered
  },
  ...
]

Each event object may contain additional properties, depending on the event.

Copy linkVersioning

Webhook events are versioned. Every webhook event contains a version attribute that indicates the version used to generate the payload. If you don't specify an API version when creating the webhook, your client API version will be the one used for generating the payload. For information on how to change the client API version, see our Versioning referenceAPI. We recommend you use the version attribute in your webhook handler to future-proof your implementation, making it easier for you to handle future version changes.

Copy linkSecurity

There are several methods you can use to ensure the security of the communication between Enode and your servers.

Copy linkPayload integrity

A cryptographically secure secret should be generated and persisted on your server.

When you call Create WebhookAPI, the secret must be provided. We use the secret to generate a signature on each webhook request. See Verifying a payload signature for instructions on using the secret to verify that the request originated from Enode.

It should be a pseudorandom value of at least 128 bits produced by a secure generator.

// Node.js example - 256 bits
const crypto = require("crypto");
const secret = crypto.randomBytes(32).toString("hex");

Copy linkVerifying a payload signature

Requests to your endpoint will bear an x-enode-signature header verifying that the request has come from us.

The signature is the HMAC hex digest of the payload, where:

• algorithm = sha1
• key = your secret provided during webhook configuration
• payload = The request body (a UTF-8 encoded string containing JSON - be sure not to deserialize it before signature computation)

The signature is then prefixed with "sha1=". A delivery of {"payload":"example"} signed with example-secret would have an x-enode-signature of sha1=e417e6fc2e7f8a78c93a35a7b344d36ce179fc8d.

In Javascript, the signature may be verified as follows:

// Node.js + Express example

// Read signature from request HTTP header
const enodeSignature = Buffer.from(req.get("x-enode-signature"), "utf8");

// Compute signature using your secret and the request payload
const payload = req.body;
const hmac = crypto.createHmac("sha1", <your secret>);
const digest = Buffer.from("sha1=" + hmac.update(payload).digest("hex"), "utf8");

// Check whether they match, using timing-safe equality (don't use ==)
if (!crypto.timingSafeEqual(digest, enodeSignature)) {
  throw new Error("Signature invalid");
}

Copy linkAuthentication

Authentication is optional. If your endpoint requires authentication, you can configure an authentication header and value pair that will be sent on every request.

You can provide authentication configuration when using the Create WebhookAPI endpoint. For existing subscriptions you can enable, update or disable authentication using the Update WebhookAPI endpoint. The header is case insensitive and will be transmitted lowercased.

Even if you have authentication configured, we strongly recommend you to verify the integrity of the request using the provided payload signature.

Copy linkIP addresses

As an additional security measure you can also verify that webhook events originate from an Enode IP address.

Webhook IP addresses are published for each environment subdomain as a TXT DNS record named webhook-ips. These IPs can change. If you are going to use them, make sure you monitor the DNS record regularly.

Run the following in your command-line to fetch the IPs:

• Production: dig +short TXT webhook-ips.production.enode.com
• Sandbox: dig +short TXT webhook-ips.sandbox.enode.com

Copy linkTimeouts, failures, and inactive webhooks

Webhook deliveries time out after 5 seconds. After a failed delivery, we will attempt to redeliver your events over 24 hours in increasing intervals. If any of the retry attempts succeeds, the webhook will be considered healthy again. But if all retry attempts fail, all pending events will be deleted and your webhook marked as inactive.

If a webhook becomes inactive, it can be reactivated in one of 2 ways:

• Use the Test WebhookAPI endpoint
• You can update the webhook using the Update WebhookAPI endpoint

Copy linkBest Practices

Copy linkHandle versioned payloads

To future-proof your implementation, we recommend that you either pin your subscription version using the Create WebhookAPI or Update WebhookAPI endpoints; or you use the version attribute in each webhook event to inform your implementation. This will ensure a graceful transition between versions.

Copy linkRespond within 5 seconds

Your server should respond with a 2XX response within 5 seconds of receiving a webhook delivery. If your server takes longer than that to respond, then Enode terminates the connection and considers the delivery a failure.

In order to respond in a timely manner, you may want to set up a queue to process webhook payloads asynchronously. Your server can respond when it receives the webhook, and then process the payload in the background without blocking future webhook deliveries.

Copy linkOnly listen to event types your integration requires

Configure your webhook endpoints to receive only the types of events required by your integration. Listening for extra events (or all events) puts undue strain on your server and we don’t recommend it.

You can change the events that a webhook endpoint receives when you createAPI or updateAPI a webhook.

Copy linkSupported events

You can find the list of supported events in the Webhook events sectionAPI of the API reference.