A webhook is a callback function that securely enables your workflows to receive events as they occur over HTTP. When an event happens in Kount 360, for example the fraud assessment status of an order is updated, we provide your webhook registration with a payload containing all pertinent information about the event.
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.
Alternatively, you can retrieve the public key from the API endpoint. Refer to the Public Key Retrieval API section.
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 event_type
is set to Order.StatusChange
and the field_name
is set to status
.
Note
Orders status update is currently the only event available.
JSON Path |
Field Name |
Description |
Type |
Examples |
id |
Event ID |
A randomly-generated UUID that identifies the event notification. |
String |
b567ec17-c5c7-40ad-8437-09b353efdb52 |
event_type |
Event Type |
A string containing the type of event that occurred out of the enumeration of possible events sent from Kount 360. One of the following enumerations (there is currently one value): |
String |
|
api_version |
API Version |
The version of the API to indicate that your API endpoint is following the latest specification. The letter "v" followed by an integer that increments with version changes. |
String |
v1 |
client_id |
Client ID |
The client ID that the event was generated for. This matches the client ID for your organization that is provided in the portal. |
String |
34510293857 |
kount_transaction_id |
Kount Order ID |
The unique identifier of the order. This allows the order to be queried and referenced in various contexts. |
String |
Y7VQBX8KTXW1V37Z |
customer_order_number |
Merchant Order ID |
The customer-provided unique identifier for this order. Uniqueness for this property is not enforced. |
String |
d121ea2210434ffc8a90daff9cc97e76 |
transaction_date |
Transaction Date |
An RFC 3339 date/time indicating when the order was placed. |
String |
2024-03-20T16:55:09.951Z |
event_date |
Event Date |
An RFC 3339 date/time indicating when the event occurred. |
String |
2024-03-21T20:44:39Z |
field_name |
Name of Updated Field |
The name of the field that was updated. |
String |
status |
old_value |
Old Field Value |
The previous value of the field before the event occurred. |
String |
REVIEW |
new_value |
New Field Value |
The new value of the field after the event occurred. |
String |
APPROVED |
{ "id": "f276e154-23ef-4366-933b-e1f12e159901", "eventType": "Order.StatusChange", "apiVersion": "v1", "clientId": "900900", "kountOrderId": "8V6CFF359HS5QQ6G", "merchantOrderId": "qjlm9gvol6olejcs", "orderCreationDate": "2022-05-24T23:13:02Z", "eventDate": "2022-05-24T23:18:00Z", "fieldName": "status", "oldValue": "REVIEW", "newValue": "DECLINE" }
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 v1.5 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
-
The Public Key Retrieval API is a REST HTTPS endpoint that uses OAuth 2.0 for authentication. It is used to retrieve the public key for our webhook system to provide validation of the message. Refer to to learn how to acquire the bearer token.
You need the {Kount Client Id}
to retrieve the public key. To get the {Kount Client Id}
:
-
Sign in to Kount 360.
-
Select Admin, and then select Product Configuration.
-
Under API Keys, copy the Client ID.
Sandbox Endpoint:
https://app-sandbox.kount.com/api/developer/ens/client/{KOUNT CLIENT ID}/public-key
Production Endpoint:
https://app.kount.com/api/developer/ens/client/{KOUNT CLIENT ID}/public-key
Method: GET
Header Authorization: Bearer <token>
Header Content-Type: application/json
Body: There is no content in the body.
JSON Path |
Field Name |
Description |
Type |
Examples |
validUntil |
Valid Until Date/Time |
An RFC 3339 date/time indicating when the public key will expire. |
String |
2025-01-03T20:39:49Z |
publicKey |
Webhook Public Key |
The public key of a RSA 4096 keypair used to validate the Kount 360 webhook messages. The value is a DER-encoded X.509 public key that has been base64 encoded (also known as SubjectPublicKeyInfo (SPKI), as defined in RFC 5280. |
String |
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAvp7nEmaR1gAD/o27TycsWJtz700RKX0czxyXKDLhx2i+9AVBgRqQLh5re36lc18KeVMTeH2Na4fTeuJ0sCtVr4Un3V3esV1V63sBIVy2ptT0wN/t4W5AttG9gXHMPNVSmhdrBiL2BTsKorIrreMpITeyVW4EMjQ0+tRrLvr0gJpp7RxrI0/xP+dVLCPWP22dXmJHzoIsAnwRKObg4glcOJqlgAagCzjkb/8fjRmEClwCSBh0bkyh7pkPhIVbFnTghAAcwgwGJMAURqqX4iRQ0Q+sJrjetUXlMLD12OGCm3xFGV/DJrRU93zN7ZG5wyjqvI/aHsx17e/SD0MkKkowNVnlS6lhB2pkZyALidHNnvIW/mEBZ8xCzUBbALmFVULeWjNNq2m/GjLI+Dvh/G4oBOwkCo26+FUKzDMWTbpZ0Fx1+p87aSdfLfE7ygrBiPUqZn7V2MwIcFs2iYc83Ghaub7yBLFWff7rmJfpDWiil/DucqcXZefEGqugFH0yhTjB8Wfb5ozrUybiwHnYV+haGlpSdUbsijIYzF+9rk3QDgcoWOQCxYQYFG0Gv7GXi3hmSKQd2sgiQjuZApGJK0971E9KpBH0V1qaDoDpiMTYwvCD4Uh//gKnu2zFxxvMqgKSwt/C+wO5uf2G/h18OWMw4P3DDMtTYjypZ5R4WNUxAqMCAwEAAQ== |
version |
Keypair Version |
The current version of the keypair, which begins at “1” and increments by one each time the keypair is rotated. |
String |
2 |
{ "validUntil": "2025-01-03T20:39:49Z", "publicKey": "MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAvp7nEmaR1gAD/o27TycsWJtz700RKX0czxyXKDLhx2i+9AVBgRqQLh5re36lc18KeVMTeH2Na4fTeuJ0sCtVr4Un3V3esV1V63sBIVy2ptT0wN/t4W5AttG9gXHMPNVSmhdrBiL2BTsKorIrreMpITeyVW4EMjQ0+tRrLvr0gJpp7RxrI0/xP+dVLCPWP22dXmJHzoIsAnwRKObg4glcOJqlgAagCzjkb/8fjRmEClwCSBh0bkyh7pkPhIVbFnTghAAcwgwGJMAURqqX4iRQ0Q+sJrjetUXlMLD12OGCm3xFGV/DJrRU93zN7ZG5wyjqvI/aHsx17e/SD0MkKkowNVnlS6lhB2pkZyALidHNnvIW/mEBZ8xCzUBbALmFVULeWjNNq2m/GjLI+Dvh/G4oBOwkCo26+FUKzDMWTbpZ0Fx1+p87aSdfLfE7ygrBiPUqZn7V2MwIcFs2iYc83Ghaub7yBLFWff7rmJfpDWiil/DucqcXZefEGqugFH0yhTjB8Wfb5ozrUybiwHnYV+haGlpSdUbsijIYzF+9rk3QDgcoWOQCxYQYFG0Gv7GXi3hmSKQd2sgiQjuZApGJK0971E9KpBH0V1qaDoDpiMTYwvCD4Uh//gKnu2zFxxvMqgKSwt/C+wO5uf2G/h18OWMw4P3DDMtTYjypZ5R4WNUxAqMCAwEAAQ==", "version": "4" }