Overview

If your store doesn't run on Shopify or WooCommerce — for example, a custom-built website, an in-house order system, or any other platform — you can still integrate with FraudHawkAI using our custom order endpoint.

Unlike the Shopify and WooCommerce integrations, this endpoint does not mirror a third-party payload shape. A custom site has no standard order format for us to map from, so this endpoint defines its own simple JSON contract. You send your order data in this format, and FraudHawkAI handles the rest — risk analysis, customer matching, and order tracking — the same as it does for Shopify and WooCommerce orders.

How it works

1. An order is created on your platform
2. You format the order data to match the FraudHawkAI custom order schema
3. You send it to the FraudHawkAI custom order endpoint with your API token
4. FraudHawkAI matches or creates the customer record, saves the order, and analyzes it for risk
5. If you send the same externalOrderId again (e.g. when order status changes), the existing order is updated instead of duplicated

---

Prerequisites

Before you begin, make sure you have:

• A FraudHawkAI account — sign up here
• Your API token — found in Dashboard → API Key
• The ability to send an HTTP POST request from your platform or backend (server-side, not client-side)

---

Endpoint

POST /api/webhooks/custom?token={your_api_token}

Query parameters

Note: Unlike the Shopify and WooCommerce integrations, this endpoint does not take a platform query parameter. There's only one payload format for custom integrations — described below — so there's nothing to select between.

---

Request body

Send a JSON body matching the schema below.

{
  "externalOrderId": "ORD-1023",
  "orderNumber": "1023",
  "customer": {
    "name": "Ali Raza",
    "email": "ali@example.com",
    "phone": "03001234567"
  },
  "amount": 4500,
  "currency": "PKR",
  "paymentType": "cod",
  "status": "pending",
  "items": [
    { "name": "Product A", "sku": "SKU1", "quantity": 1, "price": 4500 }
  ],
  "shippingAddress": {
    "city": "Lahore",
    "address1": "House #123, Street 5",
    "phone": "03001234567"
  },
  "courier": "Leopards"
}

Field reference

Important: customer.email and customer.phone are not individually mandatory, but at least one of the two is required — a request with neither is rejected. Providing customer.name alongside one of them is strongly recommended, since FraudHawkAI uses these fields to match and track customer order history across your store.

Valid status values

Any value outside this list is ignored, and the order is saved with a status of pending.

---

How duplicate requests are handled

FraudHawkAI treats externalOrderId as the unique identifier for an order from your store. If you send a request with an externalOrderId that already exists:

• The existing order is updated with the new data you sent (not duplicated)
• If the status has changed since the last request, your customer's order counters (e.g. delivered count, returned count) are adjusted automatically
• The response returns 200 OK with the message "Order updated"

If the externalOrderId is new, a new order is created and the response returns 201 Created with the message "Order saved".

This means it's safe — and expected — to call this endpoint again for the same order when its status changes, for example when it moves from pending to shipped, or from shipped to delivered.

---

Example request

curl -X POST "https://www.fraudhawkai.com/api/webhooks/custom?token=your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "externalOrderId": "ORD-1023",
    "orderNumber": "1023",
    "customer": {
      "name": "Ali Raza",
      "email": "ali@example.com",
      "phone": "03001234567"
    },
    "amount": 4500,
    "currency": "PKR",
    "paymentType": "cod",
    "status": "pending",
    "items": [
      { "name": "Product A", "sku": "SKU1", "quantity": 1, "price": 4500 }
    ],
    "shippingAddress": {
      "city": "Lahore",
      "address1": "House #123, Street 5",
      "phone": "03001234567"
    },
    "courier": "Leopards"
  }'

---

Response format

Success — new order

{
  "success": true,
  "message": "Order saved",
  "orderId": "665f1c2e9b1f2a0012a3b456"
}

Status code: 201 Created

Success — existing order updated

{
  "success": true,
  "message": "Order updated",
  "orderId": "665f1c2e9b1f2a0012a3b456"
}

Status code: 200 OK

Error responses

---

Testing your integration

1. Send a test request using the curl example above with your own API token
2. Confirm you receive a 201 response with "message": "Order saved"
3. Log in to your FraudHawkAI dashboard to see the test order appear
4. Send the same request again with the same externalOrderId and confirm you now get a 200 response with "message": "Order updated"
5. Once confirmed, connect your live order flow to send real orders as they're created and updated