How to Receive Webhooks
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 usehttp
.- 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.
IP Address | Environment |
---|---|
35.194.70.99 | sandbox |
34.86.102.227 | sandbox |
104.197.162.196 | production |
34.150.251.245 | production |
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
withContent-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:
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.
Property | API Call | Provider Alert |
---|---|---|
service |
The resource that sent the webhook: user , authentication , monitoring and so on. |
Always alerts |
path |
The API endpoint's URL. | Not present |
method |
The API endpoint's HTTP method converted to lowercase, one of post , get , put , patch , or delete . Note that this is the method of the API that triggered the webhook; it isn't the method that delivered the webhook to you (which, as mentioned, will always be POST ). |
Always push |
event |
The HTTP status of the API, presented as a string, that triggered the webhook, one of 200 , 201 , 401 , and so on. |
Always push |
details |
A JSON object that provides additional information about the event. Every event defines its own details structure. |
Updated 7 months ago