Kount 360 webhooks enable you to receive live updates over HTTP when a status change occurs. Webhook events gives you the ability to receive automated updates on orders in Kount 360. When enabled, webhook events from Kount 360 are sent to a URL hosted by you in a JSON payload.
Note
To ensure reliable webhook notifications, our system employs an automatic retry mechanism. In certain scenarios, such as network fluctuations or timeout issues, this could result in the same event payload being delivered more than once. Integrations must be designed to recognize a duplicate event and ensure that processing it multiple times does not result in inconsistent data, like creating duplicate records or double-charging a user.
The following webhook events are used in Kount 360. Webhook events are divided by product.
Payments Fraud
-
Order Update: Sends a notification when an order is approved or declined, a note added, an agent assigned, a Chargeback or Refund report is marked, and/or a reason code is added.
-
Order Status Change: Deprecated. Use Order Update instead. This webhook sends an event when an order is approved or declined.
-
Reason Code Update: This webhook sends an event notification when a reason code is added or changed.
-
Chargeback Bulk Added: Only sends a notification when a bulk chargeback report is uploaded in the user interface invoking BatchUpdateReversals.
Identity Proofing and Account Protection
-
Decision Status Update: A webhook event that sends a notification when the
decision,caseStatus,queue,rejectionCode,tags,assignee, orverifiedFraudare changed. -
Document Verification Status Update: A webhook event that sends a notification when a Multi-factor Authentication (MFA) status (
MFA.StatusUpdate) is updated.
To implement a webhook, you must:
-
Create a webhook by providing the URL to the API endpoint and selecting the events you want to be notified about. Refer to Managing Webhooks.
-
Get the public key provided in the Kount 360 portal to verify the authenticity of the events received. Kount creates an RSA 4096 key pair. The private key is used by Kount to sign the message and the public key is available to you for verifying the signature of events that your server receives.
Note
You might also need to create an IP range allowlist so that the webhook calls are allowed into your network. Go to Create an IP Range Allowlist for more information.
The workflow of the webhook call is as follows:
-
When an event with webhook support occurs in Kount 360, the system checks whether you have any webhooks configured.
-
If you have configured one or more webhooks, Kount 360 makes a call to notify your server of the event that occurred.
-
Once your server receives the HTTP request, you must use the public key that you retrieved from Kount 360 to authenticate the message.
-
Respond to the event according to your business needs.
The API endpoint you implement must be a REST HTTPS endpoint.
Method: POST
Headers: The request contains custom headers with a digital signature of the event.
With these headers, you can establish:
-
Integrity — the event has not been tampered with
-
Non-repudiation — the event was sent by Kount
|
HTTP Header |
Description |
|---|---|
|
X-Event-Signature |
A base-64 encoded RSASSA_PSS_SHA_256 signature of the event. PKCS #1 v2.2, Section 8.1, RSA signature with PSS padding that uses SHA-256 for both the message digest and the MGF1 mask generation function that includes a 256-bit salt. Go to Verifying the Signature of the Event Message to learn how to use this value to verify the signature. |
|
X-Event-Timestamp |
An RFC3339 timestamp. Example: |
Content-Type: application/json
Body: Go to Orders Update API Request Properties.
The payload depends on the event that occurs in the system.
Orders status update: This event is sent when the fraud status (approve, decline, or review) is updated. The eventType is set to Order.StatusChange and the fieldName is set to status.
It is the responsibility of your app to verify the signature of each webhook request.
-
Retrieve the webhook public key from Kount 360.
-
Extract the timestamp (
X-Event-Timestamp) and signature (X-Event-Signature) from the request headers. -
Verify that the signature timestamp is within a reasonable time frame from the current system time. For example, five minutes.
-
Reconstruct the signature by using base64 decoding.
-
Use an RSA library to verify the RSA PKCS #1 v2.2 signature. The inputs are:
-
The public key
-
SHA-256 as the hashing algorithm
-
The timestamp from the header concatenated to the body of the HTTP request (timestamp followed by the body) as the message to be verified
-
The base64 decoded signature as the signature to verify against
-
You might need to create an allowlist (formerly known as a whitelist) for webhooks to function properly on your network. Use the following IP address ranges (CIDR blocks) to create the list.
-
216.46.107.20/30
-
216.46.107.24/30
-
165.183.168.12/30
-
165.183.168.20/30
-
147.146.254.192/27
-
147.146.254.224/27
-
147.146.254.32/28
-
147.146.254.48/28
If you have any issues with the CIDR blocks, you can download a CSV file that contains a complete list of the IP addresses necessary for the allowlist.