API and webhooks

API vs Webhook

APIs are request-based, meaning they operate when requests come from 3rd party apps. Webhooks are event-based, meaning they run when a specific event occurs in the source app.

API definition

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

Think of an API like a menu in a restaurant. The menu provides a list of dishes you can order, along with a description for each dish. When you select what menu items you want, the kitchen does the work and provides you with the finished dish. You don't know exactly how the the food was prepared and you don't really need to.

Similarly, an API lists operations developers can use, along with descriptions of what they do. The developer doesn't need to know how they work, just what is available.

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 used to authenticate with UtilityManagement APIs. This will become the required way to authenticate instead of using a username and password.

Webhooks

Certain actions in UtilityManagement send automatic notifications. For example, notify me every time someone approves a bill.

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 UtilityManagement environment

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 the webhook is disabled.

Always test to ensure your endpoint works:

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

UtilityManagement Event Router

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

Webinar

A webinar on UtilityManagement's developer tools.