HomeGuidesAPI ReferenceChangelog
Log In
API Reference

Webhooks

Utility Cloud can send webhook events for any notable events for recurring requests. For example, this could include if a new statement is available or we notice a credential is now resulting in login failure.

To specify the webhook URL that you would like the events to be POSTed to, you can update it in the Console from the Configurations tab on the My Account page or using this endpoint.

When sending a webhook, Arcadia looks for a 2xx response. Arcadia assumes the webhook failed to deliver if there isn't a 2xx response. If such a response is not received, it will be assumed that the webhook failed to deliver and the Arcadia platform will continue to attempting to send the webhook response 3 times every 6 hours for a total of 1 day (12 automatic retries maximum). Each subsequent webhook attempt will have an identical message body.

There is an optional interactive boolean flag when creating new credentials. If this is set to true, a webhookUrl is required, and the system will emit Realtime-Credential-Notification (RTCV) webhook notifications confirming LOGIN_SUCCESS or LOGIN_FAILURE event types. This will also emit pending status notifications. RTCV webhooks are only retried up to 3 times.

There are endpoints for viewing and resending the webhooks stored in the system here.

Note

In the Utility Cloud architecture, Webhook events are different from EventTypes associated with a given entity (Account/Credential/Meter/Site). EventTypes are used to maintain a history of events for a particular entity. On the other hand, Webhook events are restricted to a subset of events, which are discussed here. See below for more details on various EventTypes in Utility Cloud:

Account: Account Events
Credential: Credential Events
Meter: Meter Events
Site: Site Events

Statements do not have any EventTypes associated with it, meaning there is no public event history for Statements, but there are Webhook events sent for Statements

Webhook Parameters

It is possible to optionally specify additional parameters that will be sent along with all webhooks. Namely, you can set the value of any custom headers or query parameters. This can be useful for authentication purposes to verify that a webhook is coming from Arcadia.

Currently, these values must be set by Arcadia internally and cannot be set via the API or Console. To set up these values, please reach out to customer support via Zendesk and let them know what header name(s) and value(s) are required. The maximum length of the header name is 80 characters, and the maximum length of the header value is 255 characters. Both can only contain alphanumeric characters, as well as _ and - characters. The header value can additionally contain the special characters /, ., \, and ,. Spaces are not allowed.

See below for a complete list of webhook event types with example JSON payloads:

Event Types

Event TypeSubject TypesDescription
STATUS_CHANGEACCOUNT / CREDENTIAL / FILEThis event is sent for any status changes outside of a scheduled extraction. Generally, this is because of an Arcadia employee investigating unknown issues and updating the status to reflect what the problem is. Any statuses may be sent with this event type except for PENDING (and the associated status details).
MODIFIED_STATEMENTSTATEMENTIndicates that an existing statement has been updated with modified data. Generally, this is because of updates to the extraction logic that are minor enough not to affect passing data quality audits. The ID and PDF of the statement will remain the same but the extracted data in the system will be slightly different.
NEW_STATEMENTSTATEMENTIndicates that a new statement has been initially stored for the first time. Adjustment statements are considered new statements and will have their own new and unique statement ID.
LOGIN_SUCCESSN/AThis event signifies that login was successful and no further user input is required. This webhook is only sent for credentials submitted via the API (not credentials submitted via Connect).
LOGIN_FAILUREN/AThis event signifies that login has failed and credentials must be updated. This webhook is only sent for credentials submitted via the API (not credentials submitted via Connect).
DELETION_COMPLETEDELETION_LOGThis event indicates that the deletion log was performed successfully and that the related entities have been deleted.

Webhook Notification Examples

STATUS_CHANGE

{
  "eventType": "STATUS_CHANGE",
  "subject": "CREDENTIAL",
  "status": "PENDING",
  "statusDetail": "NAVIGATION_FAILURE",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/credentials/2de4b7e7-8e14-dca4-a7bf-c629ac8775ez"
}

MODIFIED_STATEMENT

{
   "eventType": "MODIFIED_STATEMENT",
   "credentialStatus": "OK",
   "credentialStatusDetail": "NO_ACTION_REQUIRED",
   "credential": "https://api.urjanet.com/utility/credentials/3579",
   "statement": "https://api.urjanet.com/utility/statements/3579",
   "correlationId": "test-urjanet-test2022",
   "accounts": [
      {
         "id": "https://api.urjanet.com/utility/accounts/1",
         "accountNumber": "12345",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      },
      {
         "id": "https://api.urjanet.com/utility/accounts/2",
         "accountNumber": "12346",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      }
   ],
   "sites": ["https://api.urjanet.com/utility/sites/1", "https://api.urjanet.com/utility/sites/2"],
   "timestamp": "2021-02-05T16:32:16+00:00"
}

NEW_STATEMENT

{
   "eventType": "NEW_STATEMENT",
   "credentialStatus": "OK",
   "credentialStatusDetail": "NO_ACTION_REQUIRED",
   "credential": "https://api.urjanet.com/utility/credentials/3579",
   "statement": "https://api.urjanet.com/utility/statements/3579",
   "correlationId": "test-urjanet-test2022",
   "accounts": [
      {
         "id": "https://api.urjanet.com/utility/accounts/1",
         "accountNumber": "12345",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      },
      {
         "id": "https://api.urjanet.com/utility/accounts/2",
         "accountNumber": "12346",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      }
   ],
   "sites": ["https://api.urjanet.com/utility/sites/1", "https://api.urjanet.com/utility/sites/2"],
   "timestamp": "2021-02-05T16:32:16+00:00"
}

LOGIN_SUCCESS

{
  "created": "2022-09-01T17:50:13.658+00:00",
  "credentialId": "https://api.urjanet.com/utility/credentials/2de4b7e7-8e14-dca4-a7bf-c629ac8775ez",
  "correlationId": "12345",
  "eventType": "LOGIN_SUCCESS"
}

LOGIN_FAILURE

{
  "created": "2022-09-01T17:51:44.977+00:00",
  "credentialId": "https://api.urjanet.com/utility/credentials/2de4b7e7-8e14-dca4-a7bf-c629ac8775ez",
  "correlationId": "12345",
  "eventType": "LOGIN_FAILURE"
}

DELETION_COMPLETE

{
  "eventType": "DELETION_COMPLETE",
  "subject": "DELETION_LOG",
  "status": "COMPLETE",
  "statusDetail": null,
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/deletionLogs/2de4b7e7-8e14-dca4-a7bf-c629ac8775ez"
}

Example Scenarios

Successful RTCV credential submission

  1. Credentials submitted
  2. Optionally, credential login event emitted:

    📘

    This is only emitted if the credential was submitted using "interactive": true,via this endpoint.

    {
  "created": "2022-09-01T17:50:13.658+00:00",
  "credentialId": "https://api.urjanet.com/utility/credentials/<credentialId>",
  "correlationId": "12345",
  "eventType": "LOGIN_SUCCESS"
}
  3. Credential event emitted: 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "CREDENTIAL",
  "correlationId": "example",
  "status": "OK",
  "statusDetail": "NO_ACTION_REQUIRED",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/credentials/<credentialId>"
}
  4. Account(s) discovered
  5. Account event(s) emitted (1 per account under the credential): 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "ACCOUNT",
  "correlationId": "example",
  "status": "NEW_ACCOUNT",
  "statusDetail": "NO_ACTION_REQUIRED",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/accounts/<accountId>"
}
  6. Statement(s) discovered
  7. Statement event(s) emitted (1 per statement): 
    {
   "eventType": "NEW_STATEMENT",
   "credentialStatus": "OK",
   "credentialStatusDetail": "NO_ACTION_REQUIRED",
   "credential": "https://api.urjanet.com/utility/credentials/<credentialId>",
   "statement": "https://api.urjanet.com/utility/statements/<statementId>",
   "correlationId": "test-urjanet-test2022",
   "accounts": [
      {
         "id": "https://api.urjanet.com/utility/accounts/<accountId>",
         "accountNumber": "12345",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      }
   ],
   "sites": [],
   "timestamp": "2021-02-05T16:32:16+00:00"
}

Unsuccessful RTCV credential submission

  1. Credentials submitted
  2. Optionally, credential login event emitted:

    📘

    This is only emitted if the credential was submitted using "interactive": true,via this endpoint.

    {
  "created": "2022-09-01T17:50:13.658+00:00",
  "credentialId": "https://api.urjanet.com/utility/credentials/<credentialId>",
  "correlationId": "12345",
  "eventType": "LOGIN_FAILURE"
}
  3. Credential failure or pending event emitted:

    📘

    A pending event indicates that the data extraction failed for a presumably temporary reason, such as the provider website being down

    {
  "eventType": "STATUS_CHANGE",
  "subject": "CREDENTIAL",
  "correlationId": "example",
  "status": "ACTION_REQUIRED",
  "statusDetail": "LOGIN_FAILURE",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/credentials/<credentialId>"
}
    Or 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "CREDENTIAL",
  "correlationId": "example",
  "status": "PENDING",
  "statusDetail": "WEBSITE_DOWN",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/credentials/<credentialId>"
}

Successful non-RTCV credential submission

  1. Credentials submitted
  2. Credential event emitted: 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "CREDENTIAL",
  "correlationId": "example",
  "status": "OK",
  "statusDetail": "NO_ACTION_REQUIRED",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/credentials/<credentialId>"
}
  3. Account(s) discovered
  4. Account event(s) emitted (1 per account under the credential): 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "ACCOUNT",
  "correlationId": "example",
  "status": "NEW_ACCOUNT",
  "statusDetail": "NO_ACTION_REQUIRED",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/accounts/<accountId>"
}
  5. Statement(s) discovered
  6. Statement event(s) emitted (1 per statement): 
    {
   "eventType": "NEW_STATEMENT",
   "credentialStatus": "OK",
   "credentialStatusDetail": "NO_ACTION_REQUIRED",
   "credential": "https://api.urjanet.com/utility/credentials/<credentialId>",
   "statement": "https://api.urjanet.com/utility/statements/<statementId>",
   "correlationId": "example",
   "accounts": [
      {
         "id": "https://api.urjanet.com/utility/accounts/<accountId>",
         "accountNumber": "12345",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      }
   ],
   "sites": [],
   "timestamp": "2021-02-05T16:32:16+00:00"
}

Failed non-RTCV credential submission

  1. Credentials submitted
  2. Credential failure event emitted: 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "CREDENTIAL",
  "correlationId": "example",
  "status": "ACTION_REQUIRED",
  "statusDetail": "LOGIN_FAILURE",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/credentials/<credentialId>"
}

Existing credential stops working

  1. Credential login fails
  2. Credential failure event emitted: 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "CREDENTIAL",
  "correlationId": "example",
  "status": "ACTION_REQUIRED",
  "statusDetail": "LOGIN_FAILURE",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/credentials/<credentialId>"
}

New statement discovered under existing credential

📘

This also applies to adjustment statements

  1. Statement discovered
  2. Statement event emitted: 
    {
   "eventType": "NEW_STATEMENT",
   "credentialStatus": "OK",
   "credentialStatusDetail": "NO_ACTION_REQUIRED",
   "credential": "https://api.urjanet.com/utility/credentials/<credentialId>",
   "statement": "https://api.urjanet.com/utility/statements/<statementId>",
   "correlationId": "example",
   "accounts": [
      {
         "id": "https://api.urjanet.com/utility/accounts/<accountId>",
         "accountNumber": "12345",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      }
   ],
   "sites": [],
   "timestamp": "2021-02-05T16:32:16+00:00"
}

Statement data changed

  1. Data extraction updated
  2. Statement data changes
  3. Modified statement event emitted: 
    {
   "eventType": "MODIFIED_STATEMENT",
   "credentialStatus": "OK",
   "credentialStatusDetail": "NO_ACTION_REQUIRED",
   "credential": "https://api.urjanet.com/utility/credentials/<credentialId>",
   "statement": "https://api.urjanet.com/utility/statements/<statementId>",
   "correlationId": "example",
   "accounts": [
      {
         "id": "https://api.urjanet.com/utility/accounts/<accountId>",
         "accountNumber": "12345",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      }
   ],
   "sites": [],
   "timestamp": "2021-02-05T16:32:16+00:00"
}

An account is created via file upload

  1. Account discovered
  2. Account event emitted: 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "ACCOUNT",
  "status": "NEW_ACCOUNT",
  "statusDetail": "NO_ACTION_REQUIRED",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/accounts/<accountId>"
}
  3. Statement discovered
  4. Statement event emitted (1 per file uploaded): 
    {
   "eventType": "NEW_STATEMENT",
   "credentialStatus": "OK",
   "credentialStatusDetail": "NO_ACTION_REQUIRED",
   "credential": "https://api.urjanet.com/utility/credentials/<credentialId>",
   "statement": "https://api.urjanet.com/utility/statements/<statementId>",
   "correlationId": "test-urjanet-test2022",
   "accounts": [
      {
         "id": "https://api.urjanet.com/utility/accounts/<accountId>",
         "accountNumber": "12345",
         "status": "OK",
         "statusDetail": "NO_ACTION_REQUIRED"
      }
   ],
   "sites": [],
   "timestamp": "2021-02-05T16:32:16+00:00"
}

File data extraction fails

  1. File uploaded
  2. File reviewed and unable to extract data
  3. File failure event emitted: 
    {
  "eventType": "STATUS_CHANGE",
  "subject": "FILE",
  "status": "FAILURE",
  "statusDetail": "Unsupported Provider",
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/files/<fileId>"
}

Deletion complete

  1. Deletion is scheduled via deletion log. Includes deletion at the
    1. Account level (also deletes associated meters and statements)
    2. Credential level (deletes associated accounts, meters, and statements but not the credential itself)
    3. Site level (deletes a single site)
  2. Deletion is performed
  3. Deletion completed event emitted: 
    {
  "eventType": "DELETION_COMPLETE",
  "subject": "DELETION_LOG",
  "status": "COMPLETE",
  "statusDetail": null,
  "timestamp": "2022-09-07T16:15:36.428+00:00",
  "entityId": "https://api.urjanet.com/utility/deletionLogs/<deletionLogId>"
}