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 tell Array that you want to receive webhooks, you register an API endpoint -- or listener -- that you create and host on your own API server.

Registering a Listener

To register a listener, you provide your Array Customer Success representative with the listener's full 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/webhook-listener
https://prod.credit-champion.com/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 follow the same general structure:

• The message is sent as a POST with Content-Type: application/json.

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

• The message body is a JSON object that describes the event that triggered the webhook. 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 in Webhook Message Body.

Listener Response and Webhook Retry

To acknowledge the successful receipt of a webhook, your listener must return a 200 HTTP status code. If your listener (or a proxy) responds with a status other than 200, Array will resend the webhook after...

• 30 seconds
• 5 minutes
• 30 minutes
• 3 hours
• 18 hours
• 4.5 days

After 4.5 days, the webhook server gives up.

Webhook Triggers

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 value of a property depends on whether the webhook is triggered by an API call or a provider alert.