API and webhooks

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 specifc event (for example, a record update or an approval) happens in the source application, when 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).

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 UtilityManagement's APIs. This replaces traditional username and password authentication for improved security and simplicity.

Webhooks

Webhooks let you receive automatic notifications whenever certain events occur in UtilityManagement—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 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 to process webhooks and route messages to the appropriate process.

Webinar

A webinar on UtilityManagement's developer tools.