Webhook

{
    "id": 1,
    "company_id": 375,
    "event_type": "bill.created",
    "endpoint_url": "https://acmeinc.com/api/webhooks",
    "active": true,
    "archived": false,
    "created_at": "2022-02-09T17:27:23.000Z",
    "updated_at": "2022-02-09T17:27:23.000Z"
}

When you set up webhooks, EnergyPrint will ping you when certain events happen within your company’s purview. Configure an endpoint to receive and respond to simple POST requests like the following:

Example POST body

{
    "event_type": "bill.created",
    "utility_bill_ids": [253465]
}

Webhook Endpoints

List all Webhooks

GET /webhooks

Returns all your company’s webhooks.

Get a single Webhook

GET /webhooks/:id

Returns a single webhook corresponding to the provided id.

Create a Webhook

POST /webhooks

Creates a new webhook. Responds with an array containing all your company’s webhooks, including the newest one.

Example Request

{
  "event_type": "bill.created",
  "endpoint_url": "https://acmeinc.com/api/webhooks"
}

Supported Event Types

Webhooks allow you to track the following events within your EnergyPrint account.

Edit a Webhook

PUT /webhooks/:id

Edit a webhook’s event_type, active, or endpoint_url parameters.

Delete a Webhook

DELETE /webhooks/:id

Deletes a webhook.

Validating Webhooks

EnergyPrint Webhooks are validated using a BLAKE3 hash of three strings, separated by dots:

• A shared secret
• A nonce representing the current epoch time
• The body of the webhook request

i.e. "{secret}.{nonce}.{body}"

A Nodejs middleware implementation is provided below.

const blake3 = require("blake3")

const validateEpWebhook = async (req, res, next) => {
    const secret = process.env.EP_WEBHOOK_SIGNING_SECRET;

    const {data, nonce, ep_webhook_signature} = req.body;
        
    const expected_signature = await blake3.hash(
        `${secret}.${nonce}.${JSON.stringify(data)}`
    ).toString('hex');
    
    if (ep_webhook_signature === expected_signature) {
        next();
    } else {
        res.status(500).json({success: false});
    }
}

Getting your secret

Using your API token, getting your shared webhook secret is simple.

GET /webhooks/validate

Resetting your secret

At some point in the future, you may want to reset your shared webhook secret.

POST /webhooks/validate/reset

Responds with the new secret.