A webhook is an HTTP message that's sent to you by Array when a specific event occurs, such as when a customer enrolls in Array, orders a credit report, receives an Identity Protect alert, and so on. To receive these messages, you create an API endpoint -- or "listener" -- that you host on your own API server, and then register the listener's full URL with Array.

Registering a Listener

To register a listener, you provide your Array sales engineer or Customer Success representative with the listener's URL. It's recommended that you register two listeners, one for webhooks that are sent when events occur in the Array sandbox and another for production. For example:

https://sandbox.credit-champion.com/array-webhook-listener
https://prod.credit-champion.com/array-webhook-listener

There's nothing special about the sandbox and prod subdomain names that are used in the example: They don't magically map to the sandbox and production environments. In fact, the listeners don't have to be in separate subdomains at all. You can use the same subdomain and differentiate the listeners by resource name:

https://dev.credit-champion.com/array-sandbox-listener
https://dev.credit-champion.com/array-prod-listener

🚧

• The webhook listener scheme must be https. You can't use http.
• You may register only one listener per environment.

Array Webhook Server IP Addresses

The IP addresses of the Array servers that send the webhook messages to your listener are listed below.

These addresses are subject to change without notice.

Webhook Message Structure

All webhook messages that your listener will receive follow the same general structure:

• The messages are sent as POSTs. Thus, the implementation of your listener API (the webhook-listener endpoint shown in the example, above), only needs to respond to POST messages.

• The body of the webhook message is a JSON object that carries information about the event. All event objects follow the same structure: A set of common properties that describe how the webhook was triggered, and a set of custom properties that describe the event. We'll take a closer look at the object later in this documentation.

• The message doesn't contain query parameters or custom headers.

• You're not expected to send a response message (and they're ignored if you do).

Webhook Event Types

Webhooks are triggered by two types of events:

• API calls. These are events that correspond to specific Array APIs. For example, the "customer ordered a report" webhook is sent when the Order a Credit Report API is invoked (even if the API was invoked from an Array component). For a list of webhooks that are triggered by the Array API, see API Webhooks. In addition, every API specification lists and describes the webhooks that it sends [[WIP]].

• Provider alerts. Some webhooks are triggered by events that are detected by the credit bureaus and Identity Protect. See the following sections for the alerts that originate from the credit bureaus and Identity Protect:

  • TransUnion Standard Alerts
  • TransUnion Enhanced Alerts
  • Equifax Alerts
  • Experian Alerts
  • Identity Protect Alerts

🚧

You can't pick and choose the webhooks events that you're interested in. After you've registered a listener, it will begin receiving all webhooks that are triggered within the designated environment (sandbox or production).

Webhook Message Body

The example below demonstrates the form of the JSON object that you'll receive in the body of a webhook message:

{
  "service": "authenticate",
  "event": "200",
  "method": "get",
  "path": "/api/authenticate/v2",
  "details": {
    "appKey": "9e864007-e5ee-4f51-b44a-2bfe1acb8e89",
    "clientKey": "1q7nWv4CC0Su9b3P8BqAtbnaah7",
    "authToken": "135409c0-e5ff-4f4f-8b7f-4672605f6aaf",
    "bureau": "tui"
  }
}

The values that the properties take and what they mean depends on whether the webhook is triggered by an API call or a provider alert.