Webhook Integration

Webhooks are available to notify you when an alert (or other notifications) comes in so that you can message users in whatever fashion you wish to return to your site.

Implementing webhooks is optional and the same for each of the 3 integration options. If the customer wants to send notifications to their users, then they need to set up their webhook, which is where we will send their users' notifications as http requests. For their reference while setting this up, the Test API Postman Collection has an example demonstrating how their webhook should respond to the requests that CRS sends to it. When their webhook is ready, they send us the webhook URL, username, password -- This info is added to their configuration so that their webhook URL receives all their users' notifications (in production notifications are sent in nightly batches). The Test API Postman Collection also has a request that will trigger our server to send a webhook to the URL that we have set up for their host configuration so the customer can see that their webhook is behaving correctly. The required behavior for the customer's Webhook is specified below.

To get started, please provide us a URL endpoint to push the webhook to.

The webhook should implement SSL and Basic HTTP Authentication, so we need a username and password to the endpoint (15-char or less, it's not super secure and probably doesn't need to be).

The basic JSON for the web hook will look like the following (not all fields are present with all requests):

    id: "String - Webhook ID, UUID format",
    type: "String - Webhook Type, see possible values below",
    user_id: "String - CRS user ID, UUID format",
    host_id: "String - The host configuration generating the webhook, UUID format",
    time: "long - Linux epoch, seconds since 1/1/1970",
    error_code: "String - used to report host errors, future use at the moment",
    error_msg: "String - error code details"
    alert_id: "String - id for retrieving additional alert details when available",
    alert_date: "Date - the date/time the alert was reported",
    alert_source: "String - name of the institution reporting when available"

When a webhook is received, a response is needed. Responses with a status other than true will cause the webhook to be resent.

    hook_id: "the ID of the webhook",
    status: true | false

Webhook Type Values

  • ACCNEW - New Account Created (only sent when created via web, not direct)
  • IDFAIL - Identity Failed (user identification process failed)
  • ACCREG - Account Registered (user passed identification and is registered for data)
  • ACCREGFAIL - Account Registration Failed (user passed identification, but was unable to register for data)
  • ACCCLOSED - Account Closed (only sent when completed via web, not direct)
  • ACCLOCKED - Account Locked Out (account is temporarily locked out)
  • ACCLOGINFAIL - Login Failure (when user authentication fails, web only)
  • ACCALERT - Account Alert (when credit alert notifications, both daily and real-time)
  • SCOREREF - User Score has been refreshed
  • REPORTREF - User Report has been refreshed
  • ERROR - Error (report important issues that may be of interest)
  • TEST - Test (testing notification)
Additional webhooks may be added without notice

Consumer Credit - Test API.postman_collection.json includes some webhook tests to help you understand and develop your solution. Once your host is configured, you can use Webhook Test to send a test webhook for a user on demand. See the Test API for additional documentation.