In the UtilityAPI dashboard, configure a webhook endpoint URL under Settings > Webhooks; UtilityAPI will POST a JSON payload to this URL when meter data collection completes or when a new authorization is created.
Validate incoming webhook requests by checking the UtilityAPI-Signature header against an HMAC-SHA256 of the raw request body using your webhook secret; reject requests where signatures do not match to prevent spoofed callbacks.
Parse the webhook payload: the 'event' field identifies the event type (e.g., 'meters.updated', 'authorizations.updated'); for 'meters.updated', extract the 'meters' array containing meter UIDs that have new data available.
For each meter UID in the webhook payload, call GET /api/v2/meters/{uid}/intervals to retrieve the newly available interval data; use the 'updated_since' query parameter set to the webhook's timestamp to fetch only new intervals rather than re-downloading all historical data.
Implement idempotent processing: UtilityAPI may deliver the same webhook more than once (at-least-once delivery); use the 'uid' field from the payload as a deduplication key and check whether the event has already been processed before performing downstream actions.
Respond to the webhook POST with HTTP 200 within a few seconds; perform heavy processing asynchronously in a background job — a slow or error-returning response will trigger UtilityAPI's retry logic with increasing backoff.
Known gotchas
UtilityAPI data collection is asynchronous and may take minutes to hours depending on the utility's data availability; do not poll the intervals endpoint immediately after creating an authorization — wait for the webhook event before fetching data to avoid empty responses and unnecessary API calls.
The 'meters.updated' webhook fires when any data attribute changes, not only when new interval data arrives; check the meter's 'intervals_updated' timestamp in the webhook payload to confirm new interval data is actually present before calling the intervals endpoint.
Interval data for some utilities arrives in non-chronological order across multiple webhook deliveries as UtilityAPI backfills historical data; your storage layer should upsert intervals by their start timestamp rather than assuming append-only delivery.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp