Quick Links

Implementing a Webhook Notification

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, or verifiedFraud are 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:

  1. 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.

  2. 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.

Webhook Workflow

The workflow of the webhook call is as follows:

Kount_360_Webhooks.svg
  1. When an event with webhook support occurs in Kount 360, the system checks whether you have any webhooks configured.

  2. If you have configured one or more webhooks, Kount 360 makes a call to notify your server of the event that occurred.

  3. Once your server receives the HTTP request, you must use the public key that you retrieved from Kount 360 to authenticate the message.

  4. Respond to the event according to your business needs.

Webhook Specification

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: 2024-03-20T16:55:09.951Z

Content-Type: application/json

Body: Go to Orders Update API Request Properties.

Request Parameters and Data Submission

Caution

If you are implementing a webhook for Chargeback Management, do not use the Channel field.

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.

Webhook response

The webhook should return an HTTP 200 if the webhook call was successful. Any other response is considered a failure. No headers or body is expected in the response.

Verifying the Signature of the Event Message

It is the responsibility of your app to verify the signature of each webhook request.

  1. Retrieve the webhook public key from Kount 360.

  2. Extract the timestamp (X-Event-Timestamp) and signature (X-Event-Signature) from the request headers.

  3. Verify that the signature timestamp is within a reasonable time frame from the current system time. For example, five minutes.

  4. Reconstruct the signature by using base64 decoding.

  5. Use an RSA library to verify the RSA PKCS #1 v2.2 signature. The inputs are:

    1. The public key

    2. SHA-256 as the hashing algorithm

    3. The timestamp from the header concatenated to the body of the HTTP request (timestamp followed by the body) as the message to be verified

    4. The base64 decoded signature as the signature to verify against

Webhook Handler Examples

The following examples demonstrate how to verify the signature of the event message in Go and TypeScript.

Create an IP Range Allowlist

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.

Was this article helpful?
0 out of 4 found this helpful