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 POST 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 POST 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'
info:
 title: Fraugster webhook
 version: '1.0'
components:
 schemas:
   manualReviewData:
     properties:
       frg_trans_id:
         type: string
         description: Transaction ID generated by Fraugster
       trans_id:
         type: string
         description: Transaction ID received from the client
       decision:
         type: string
         description: The decision taken during the manual review
       reviewed_at:
         type: string
         description: The time when the transaction was manually reviewed
         format: date-time
   webhook:
     properties:
       type:
         type: string
         description: Type of event
         enum: [txn_manual_review]
       data:
         oneOf:
           - $ref: '#/components/schemas/manualReviewData'
paths:
 /{customer_provided_URL}:
   post:
     parameters:
       - in: header
         name: X-FraugsterWebhook-Signature
         schema:
           type: string
           description: Signature of the whole message.
         required: true
       - in: header
         name: X-FraugsterWebhook-Timestamp
         schema:
           type: string
           description: UNIX timestamp of request.
         required: true
     requestBody:
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/webhook'
     responses:
       '200':
         description: OK

Guarantees

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 Admin → Webhooks.
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 Admin → Webhooks → Activity 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.