Implementing a Webhook Notification

Implementing a Webhook Notification

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:

  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.

    Alternatively, you can retrieve the public key from the API endpoint. Refer to the Public Key Retrieval API section.

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

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.

Orders Update API Request Properties

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): Order.StatusChange

String

Order.StatusChange

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

Orders Update API Example

{
  "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"
}

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 v1.5 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.

Public Key Retrieval API

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}:

  1. Sign in to Kount 360.

  2. Select Admin, and then select Developer.

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

Public Key API Response Properties

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

Public Key API Response Example

{
  "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"
}
Was this article helpful?
0 out of 0 found this helpful