API and webhooks

Last updated August 27, 2026

API vs Webhook

APIs are request-based. They operate when a third-party application (the "client") sends a request to the API (the server).

Webhooks are event-based. They operate when a specific event (for example, a record update or an approval) happens in the source application, which then automatically pushes data to another service or application.

API definition

An Application Programming Interface (API) lets two applications talk to each other.

An API (Application Programming Interface) is essentially a contract that defines how two software systems interact. It:

  • Lists the available operations (endpoints) and their purposes.
  • Doesn’t require detailed knowledge of how those operations are executed behind the scenes.
  • Functions like a restaurant menu—pick what you want (send a request), and the kitchen (server) returns your order (response).

API example

When you click the Pay with PayPal button, your shopping cart sends an order request to the PayPal API. A pop-up authenticates you and confirms the purchase. If everything goes to plan, the API sends confirmation of payment back to the application (your shopping cart).

API key

An API key is a secure credential used to authenticate calls to EnergyCAP's APIs. This replaces traditional username and password authentication for improved security and simplicity.

Create an API key

  1. From the Settings menu select API Keys and Webhooks.
  2. In the API Keys card, click the plus sign to create a new key.
  3. Enter the name of the key and a description.
  4. Click Save.
  5. Make sure to copy the key before closing the dialog. You will not be able to see it again.
  6. Click Close.

 

Webhooks

Webhooks let you receive automatic notifications whenever certain events occur in EnergyCAP—for example, "notify me when a bill is approved."

You can decide what actions to be notified about.

Webhooks are a way to receive information when it happens, rather than continually polling for the data and receiving nothing most of the time.

  • Typically are used to connect two different applications.
  • Are user-defined HTTP callbacks which are triggered by specific events. Whenever the trigger event occurs in the source site, the webhook sees the event, collects the data, and sends it to the specified URL.
  • More efficient than using an API to poll the application for the event.

Use a webhook to

  • Run a script
  • Send an email
  • Kick off automation
  • Run reports
  • Trigger automation with the EnergyCAP environment

Create a webhook

  1. From the Settings menu select API Keys and Webhooks.
  2. In the Webhooks card, click the plus sign to create a new key.
  3. Enter the required fields for the webhook.
    1. When creating the webhook name it is helpful to include the workflow it is a part of or the name of the third-party integration.
    2. The Secret is used to validate that the message is from EnergyCAP. 
  4. Click Save.

Disabled webhooks

A webhook is disabled when it fails too many times in a row. Webhook failure is often a result of improper configuration or an unreachable endpoint. After you correct any problems with the configuration and verify the endpoint exists and is available, you can re-enable the webhook.

Webhook execution occurs asynchronously and failures may not be obvious to you until the webhook is disabled.

Always test to ensure your endpoint works:

  • During initial creation.
  • After taking the webhook live.
  • After making any changes.

EnergyCAP Event Router

A centralized tool to process webhooks and route messages to the appropriate process.

Webinar

A webinar on EnergyCAP's developer tools.