Receive Real-Time Fraud Alerts via AntifraudAI Webhooks

Instead of polling the AntifraudAI API to check on transaction outcomes or case status changes, webhooks let AntifraudAI push events to your server the moment they happen. This enables real-time alerting, automated case triage workflows, and instant order fulfilment or cancellation — all without a single polling loop.

Supported Webhook Events

Event	Triggers when
`transaction.screened`	A transaction screening completes (any decision)
`transaction.blocked`	A transaction receives a `block` decision
`case.created`	A new case is opened for manual review
`case.resolved`	A case is approved or rejected by an agent or automation
`rule.triggered`	A custom rule fires during screening

Creating a Webhook

Open the Webhooks settings

In the AntifraudAI dashboard, navigate to Settings → Webhooks and click Add Endpoint.

Enter your endpoint URL

Provide a publicly accessible HTTPS URL on your server. AntifraudAI will send HTTP POST requests to this URL for each subscribed event.

Select events to subscribe to

Check the events you want to receive. You can subscribe to individual events or use “Send all events” to receive everything.

Save and copy the signing secret

Click Save. AntifraudAI will display a signing secret (prefixed whsec_). Copy it now — it will not be shown again. Store it securely in your environment variables and use it to verify incoming webhook signatures.

Webhook Payload

AntifraudAI delivers events as JSON POST requests. Below is an example payload for the transaction.screened event:

{
  "event": "transaction.screened",
  "created_at": "2024-03-15T10:23:46Z",
  "data": {
    "transaction_id": "txn_9f8e7d6c",
    "risk_score": 68,
    "decision": "review",
    "user_id": "usr_abc123"
  }
}

Field	Description
`event`	The event type string (see table above)
`created_at`	ISO 8601 timestamp of when the event was generated
`data`	Event-specific payload — contents vary by event type

Verifying Webhook Signatures

AntifraudAI signs every webhook request using HMAC-SHA256 and includes the signature in the X-AntifraudAI-Signature HTTP header. You must verify this signature before processing the payload. The signature is computed as:

HMAC-SHA256(signing_secret, raw_request_body)

Always verify the webhook signature before processing the payload. Skip this check and you risk processing forged requests crafted by a third party to manipulate your fraud operations workflow.

import hashlib
import hmac

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    """Return True if the webhook signature is valid."""
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)


# Example usage inside a Flask view
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_signing_secret"

@app.route("/webhooks/antifraudai", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-AntifraudAI-Signature", "")
    if not verify_webhook(request.data, signature, WEBHOOK_SECRET):
        abort(400, "Invalid signature")

    payload = request.get_json()
    event = payload["event"]

    if event == "transaction.screened":
        handle_transaction_screened(payload["data"])
    elif event == "case.created":
        handle_case_created(payload["data"])

    return "", 200

import crypto from "crypto";
import express from "express";

const app = express();
const WEBHOOK_SECRET = "whsec_your_signing_secret";

function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signatureHeader, "hex")
  );
}

// Use express.raw() to preserve the raw body for signature verification
app.post(
  "/webhooks/antifraudai",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.headers["x-antifraudai-signature"] ?? "";

    if (!verifyWebhook(req.body, signature, WEBHOOK_SECRET)) {
      return res.status(400).send("Invalid signature");
    }

    const payload = JSON.parse(req.body.toString());

    if (payload.event === "transaction.screened") {
      handleTransactionScreened(payload.data);
    } else if (payload.event === "case.created") {
      handleCaseCreated(payload.data);
    }

    res.status(200).send("OK");
  }
);

Use a constant-time comparison (e.g. hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js) when comparing signatures. Standard string equality is vulnerable to timing attacks.

Retries

If your server does not return a 2xx HTTP status code within 30 seconds, AntifraudAI considers the delivery attempt failed and will retry using exponential backoff:

Attempt	Delay after previous failure
1 (initial)	Immediate
2	~30 seconds
3	~5 minutes
4	~30 minutes
5	~2 hours

After 5 failed attempts, the delivery is marked failed and no further retries are made. You can inspect failed deliveries and manually replay them from Settings → Webhooks → [Your Endpoint] → Delivery Logs.

Make your webhook handler idempotent — the same event can be delivered more than once if a retry occurs after your server processed the event but before it returned 200. Use the transaction_id or case_id in the payload as a deduplication key.

Get Started

Core Concepts

Guides

Configuration

Help

Receive Real-Time Fraud Alerts via AntifraudAI Webhooks

Supported Webhook Events

Creating a Webhook

Webhook Payload

Verifying Webhook Signatures

Retries

​Supported Webhook Events

​Creating a Webhook

​Webhook Payload

​Verifying Webhook Signatures

​Retries

Supported Webhook Events

Creating a Webhook

Webhook Payload

Verifying Webhook Signatures

Retries