Skip to main content

Fraugster webhook

Fraugster uses webhooks to notify your application when an event happens in your Fraugster account. A successful integration allows you to receive event notifications so your application can automatically trigger specific actions.

Webhooks are particularly useful for asynchronous events. At the moment, you can use the webhook to get notified when a transaction has been manually reviewed and given a decision. We're working on other applications of the tool. Stay tuned!

Want to give it a try?

If you'd like to start using the webhook functionality, please contact our Customer Support team at [email protected].

Build a webhook endpoint

Start adding webhooks to your Fraugster integration by building your own endpoint. At a minimum, implement an endpoint that expects data through a request and confirms successful receipt of the data with a 200 status code without a delay.

Process incoming webhooks

For each event occurrence, Fraugster sends a request with the webhook data to your endpoint in JSON format. The full event details are included and can be used directly after parsing the request body and headers into an Event object.

When you receive the request, parse the body and headers to validate that request is coming from Frausgter. The HTTP request may have multiple headers, but only these two are important for the event:

  • X-FraugsterWebhook-Timestamp - a timestamp indicating when the request was sent. This is the date-time notation as defined by RFC 3339, section 5.6, for example, 2017-07-21T17:32:28Z. To prevent replay attacks, validate that the timestamp is not too old, for example not older than 5 minutes.
  • X-FraugsterWebhook-Signature - a signature of the whole message including the timestamp, message body, and secret key. You generate a signature for each incoming webhook and check it against the signature you receive from Fraugster.

Depending on the event type, the JSON body may contain a variety of fields. These two fields, however, are required:

  • type (string) - the type of the event.
  • data (JSON object) - the data that comes with the event and depends on it.

Example of a JSON body

"type": "txn_manual_review",
"data": {
"frg_trans_id": "82d26bf0-a6eb-45f2-855d-76a590852f25",
"trans_id": "d72xfdil915889fu",
"decision": "good",
"reviewed_at": "2021-07-12T12:20:50Z"

The field decision may take one of the following values only. The values reflect the manual review decision user submits for a transaction:

  • good
  • probably_good
  • suspicious
  • bad

Here's an overview of all the fields that you may expect in a response:

openapi: '3.0.2'
title: Fraugster webhook
version: '1.0'
type: string
description: Transaction ID generated by Fraugster
type: string
description: Transaction ID received from the client
type: string
description: The decision taken during the manual review
type: string
description: The time when the transaction was manually reviewed
format: date-time
type: string
description: Type of event
enum: [txn_manual_review]
- $ref: '#/components/schemas/manualReviewData'
- in: header
name: X-FraugsterWebhook-Signature
type: string
description: Signature of the whole message.
required: true
- in: header
name: X-FraugsterWebhook-Timestamp
type: string
description: UNIX timestamp of request.
required: true
$ref: '#/components/schemas/webhook'
description: OK


Confirmation of receipt

To acknowledge receipt of an event, your endpoint must return a 200 status code to Fraugster. All response codes outside the 2xx range indicate that you didn't receive the event, or there was an error.

The majority of webhook issues result in 4xx and 5xx status codes. 4xx indicates Fraugster was able to contact your server, but the endpoint was not valid. 5xx is usually the result of a problem on your server.

It's very important to acknowledge the receipt of the webhook notification as soon as possible, so we advise you configure your endpoint to return a 200 status code without a delay, prior to any complex logic that could cause a timeout.

Delivery attempts and retries

If Fraugster doesn't receive a 200 status code, the notification attempt is repeated. The retry mechanism follows an exponential backoff algorithm starting at 5 seconds. After multiple failures to send the notification over 8 retry attempts (approximately 4,5 days), Fraugster marks the event as failed and stops trying to send it to your endpoint.

With every retry the timestamp and signature are recalculated. Your webhook endpoint may occasionally receive the same event more than once, so we advise you make your event processing idempotent.

Order of events

Fraugster doesn't guarantee delivery of notifications in the order in which events are generated.

Test a webhook endpoint

You can test your local endpoint using a command like this:

curl -X POST \
'https://localhost:4040/webhook' \
-H 'Accept: */*' \
-H 'X-FraugsterWebhook-Timestamp: 2021-07-12T12:25:50Z' \
-H 'X-FraugsterWebhook-Signature: RkOXiWX/zsbm1zs2o5rkPOsV9++BMbgweGLrxWDn+Yg=' \
-H 'Content-Type: application/json' \
-d '{
"type": "txn_manual_review",
"data": {
"frg_trans_id": "82d26bf0-a6eb-45f2-855d-76a590852f25",
"trans_id": "d72xfdil915889fu",
"decision": "good",
"reviewed_at": "2021-07-12T12:20:50Z"

Check webhook signatures

Signatures help you verify that events your endpoint is receiving are sent by Fraugster, not by a third party. Fraugster signs the webhook events by including a signature in each event’s X-FraugsterWebhook-Signature header.

A signature is a hash-based message authentication code (HMAC). Fraugster involves data in a specific order to generate a signature:

  1. Creates an HMAC-SHA256 hash with the secret key.
  2. Adds the byte array of the timestamp to the hash.
  3. Adds the byte array of the request body to the hash.
  4. Gets the resulting hash as a hexadecimal encoded string (signature).

Complete this process on your end to generate a signature that you need to compare against the signature Fraugster sends in X-FraugsterWebhook-Signature of the header. Before you can verify signatures, you need to retrieve your endpoint’s secret key from your Fraugster account:

  1. Log in to your Fraugster account.
  2. Go to AdminWebhooks.
  3. Find the secret key next to the target URL of the webhook.

Fraugster generates a unique secret key for each endpoint.

View events in the Dashboard

Activity log for all events is available in the Dashboard. Navigate to AdminWebhooksActivity log to find information about a specific event and its status. You can sort the events by status or type; a date range selection is also available.