Custom/Native Integration Guide

complete guide for integrating your custom commerce backend with forter agentic orchestration this guide is for merchants who have built their own commerce solution and manage their own backend, inventory, and order processing for shopify or sfcc, see docid\ bjwnwn2n w7estjevmtuw or docid\ c1idaysukjibep7qk oh how it works with custom integration, you host a product feed at a stable url (google merchant center xml, shopify csv, or json file) implement a webhook endpoint to receive completed orders from forter process orders in your backend system forter fetches your feed periodically (hourly, daily, or custom schedule) generates and maintains the ai optimized product data handles the checkout flow and calls your webhook when orders are complete you provide feed url + webhook endpoint you implement order processing webhook handler prerequisites before starting, ensure you have product feed — google merchant center xml, shopify csv, or json format hosted at a stable url backend system — ability to receive and process webhook post requests https endpoint — webhook url must use https forter account — contact your forter representative to enable agentic orchestration tax configuration — list of us states where you have tax nexus step 1 host your product feed a feed format options choose one of the supported formats google merchant center xml \<?xml version="1 0" encoding="utf 8"?> \<rss version="2 0" xmlns\ g="http //base google com/ns/1 0"> \<channel> \<title>your store\</title> \<link>https //yourstore com\</link> \<description>product feed\</description> \<item> \<g\ id>sku 001\</g\ id> \<g\ title>premium widget\</g\ title> \<g\ description>high quality widget for all your needs\</g\ description> \<g\ link>https //yourstore com/products/widget\</g\ link> \<g\ image link>https //yourstore com/images/widget jpg\</g\ image link> \<g\ price>29 99 usd\</g\ price> \<g\ availability>in stock\</g\ availability> \<g\ brand>mycustomstore\</g\ brand> \<g\ gtin>1234567890123\</g\ gtin> \<g\ condition>new\</g\ condition> \</item> \<! more products > \</channel> \</rss> shopify csv handle,title,body (html),vendor,product category,type,tags,published,option1 name,option1 value,variant sku,variant grams,variant inventory tracker,variant inventory qty,variant inventory policy,variant price,image src,variant image,variant barcode widget premium,premium widget,"\<p>high quality widget\</p>",mycustomstore,,widgets,"gadgets,premium",true,,,sku 001,500,shopify,100,deny,29 99,https //yourstore com/widget jpg,,1234567890123 b host feed at stable url host your feed file at a publicly accessible url examples \ https //yourstore com/feeds/products xml \ https //cdn yourstore com/feed xml \ https //s3 amazonaws com/yourbucket/feed xml (with public access or pre signed url) requirements must be https must return content type application/xml (for xml) or text/csv (for csv) file size limit 500mb response time < 30 seconds c feed authentication (optional) if your feed requires authentication http basic auth (supported) username your username password your password forter will send authorization basic base64(username\ password) other authentication methods if your feed url requires other authentication methods (e g , bearer token, api key header, custom authentication), contact your forter representative to configure the credentials securely forter can support custom authentication headers on a case by case basis step 2 implement webhook endpoint create an https endpoint to receive completed orders from forter a webhook request format forter will post json to your webhook url when an order is completed endpoint post https //yourstore com/webhooks/forter orders headers content type application/json {your store name} signature hmac sha256=abc123 payload { "event" "order created", "order" { "id" "order abc123", "number" "1001", "created at" "2026 02 09t12 00 00z", "currency" "usd", "total" "65 98", "subtotal" "59 98", "tax" "6 00", "shipping" "0 00", "customer" { "email" "customer\@example com", "first name" "john", "last name" "doe", "phone" "+14155551234" }, "line items" \[ { "sku" "sku 001", "product id" "prod 123", "title" "premium widget", "quantity" 2, "price" "29 99", "total" "59 98" } ], "shipping address" { "name" "john doe", "line one" "123 main st", "line two" "apt 4", "city" "san francisco", "state" "ca", "country" "us", "postal code" "94102", "phone" "+14155551234" }, "billing address" { "name" "john doe", "line one" "123 main st", "city" "san francisco", "state" "ca", "country" "us", "postal code" "94102" }, "payment reference" "forter txn xyz789", "payment status" "paid", "fulfillment status" "unfulfilled" } } b verify webhook signature important always verify the hmac signature to ensure the request is from forter \# python example import hmac import hashlib def verify signature(payload, signature, secret) computed = hmac new( secret encode('utf 8'), payload encode('utf 8'), hashlib sha256 ) hexdigest() expected = f"hmac sha256={computed}" return hmac compare digest(expected, signature) \# usage payload body = request body # raw request body signature header = request headers get('your store name signature') webhook secret = os environ get('forter webhook secret') if not verify signature(payload body, signature header, webhook secret) return 401 # unauthorized // node js example const crypto = require('crypto'); function verifysignature(payload, signature, secret) { const computed = crypto createhmac('sha256', secret) update(payload) digest('hex'); const expected = `hmac sha256=${computed}`; return crypto timingsafeequal( buffer from(expected), buffer from(signature) ); } // usage const payloadbody = req body; // raw request body const signatureheader = req headers\['your store name signature']; const webhooksecret = process env forter webhook secret; if (!verifysignature(payloadbody, signatureheader, webhooksecret)) { return res status(401) send('unauthorized'); } c process order and respond after verifying the signature, process the order in your system create order in your database charge payment (if not already charged by forter) update inventory send confirmation email respond with success required response { "success" true, "order id" "your internal order id", "order number" "your order number", "permalink url" "https //yourstore com/orders/12345" } error response (if order creation fails) { "success" false, "error code" "inventory unavailable", "error message" "product sku 001 is out of stock" } response requirements http status 200 (for success) or 400 500 (for errors) response time < 10 seconds content type application/json step 3 configure in forter portal log in to the forter portal and navigate to integrations > custom a basic store information field description example store title your store name "my custom store" store url your storefront url "https //www mycustomstore com" logo url url to your logo "https //www mycustomstore com/logo png" currency primary currency "usd" origin country shipping origin "us" origin region state/region "ca" b feed configuration field description example required feed url url to your hosted product feed "https //mycustomstore com/feed xml" yes feed format format of your feed "google" (google merchant center xml) yes update frequency how often to fetch every 24 hours yes feed active enable automatic fetching true yes feed username http basic auth username "api user" optional feed password http basic auth password •••••••• (encrypted) optional c webhook configuration field description example required checkout webhook url your endpoint for orders "https //mycustomstore com/webhooks/orders" yes webhook secret secret for hmac signatures auto generated or custom yes webhook auth mode authentication method "hmac" yes webhook secret forter will generate a random secret key store this securely you'll need it to verify webhook signatures d store policies field description terms of service url link to your terms privacy policy url link to your privacy policy return policy url link to your return policy return window (days) days allowed for returns (e g , 30 ) e tax configuration field description example tax nexus regions us states where you collect sales tax \["ca", "ny", "tx"] f order status url (optional) field description example order status url template url for order tracking "https //mycustomstore com/orders/{order id}" the {order id} placeholder will be replaced with your order id from the webhook response step 4 payment & fraud settings (optional) by default, you handle payment validation and authorization in your webhook handler this section is only needed if you want forter to handle fraud detection and payments option a merchant side validation/authorization (default) what happens forter calls your webhook with order details and payment reference your webhook processes payment through your payment provider your webhook handles fraud checks through your existing rules configuration no additional setup needed this is the default behavior settings in portal enable forter validation false (default) enable forter authorization false (default) enable forter capture false (default) option b forter side validation/authorization (optional) what happens forter validates orders for fraud before calling your webhook forter authorizes/captures payments via forter payment orchestration your webhook receives orders with completed payment status configuration required contact your forter representative to obtain field description validation api key forter fraud detection credentials payment api key forter payment orchestration credentials settings in portal enable forter validation true enable forter authorization true enable forter capture true (or false for manual capture) step 5 testing a test feed fetch after configuring the feed url forter attempts to fetch your feed check forter portal logs for fetch status verify products appear in the portal common issues 403 forbidden check feed url is publicly accessible timeout ensure feed responds within 30 seconds parse error validate xml/csv format b test webhook endpoint use curl to simulate a webhook call \# generate test signature secret="your webhook secret" payload='{"event" "order created","order" {"id" "test 123"}}' signature=$(echo n "$payload" | openssl dgst sha256 hmac "$secret" | awk '{print "hmac sha256="$2}') \# send test webhook curl x post https //yourstore com/webhooks/forter orders \\ h "content type application/json" \\ h "your store name signature $signature" \\ d "$payload" expected response { "success" true, "order id" "test order 123", "order number" "test 001", "permalink url" "https //yourstore com/orders/test order 123" } c end to end checkout test test the complete checkout flow \# 1 create checkout session curl x post \\ https //{site id} agentic checkouttools com/checkout sessions \\ h "authorization bearer sk test your api key" \\ h "content type application/json" \\ d '{ "items" \[{ "id" "sku 001", "quantity" 1 }], "buyer" { "first name" "test", "email" "test\@example com" } }' \# 2 complete order curl x post \\ https //{site id} agentic checkouttools com/checkout sessions/{session id}/complete \\ h "authorization bearer sk test your api key" \\ h "content type application/json" \\ d '{ "fulfillment address" { "name" "test user", "line one" "123 test st", "city" "san francisco", "state" "ca", "postal code" "94102", "country" "us" }, "payment data" { "token" "tok test visa 4242", "provider" "test" } }' 3\ verify webhook was called check your server logs verify order was created in your system confirm response was sent back to forter step 6 go live production checklist replace test credentials with production credentials verify production feed url is accessible test webhook endpoint with production domain verify https certificate is valid configure monitoring and error alerting test at least one production order end to end enable ai platform distribution (openai, google, etc ) monitoring use the forter portal to monitor feed health — fetch status, product count, parse errors webhook success — delivery rate, response times, errors order volume — checkout sessions, completions, failures error rates — failed webhooks, timeouts troubleshooting feed not fetching solution verify feed url returns 200 ok check content type header is correct ensure feed size is under 500mb test feed url in browser review forter portal logs for specific errors webhook signature verification failing solution verify webhook secret matches portal configuration check you're using the raw request body (not parsed json) ensure signature header name matches your store name use crypto timingsafeequal() for comparison (prevents timing attacks) webhook timeouts solution process order asynchronously (return 200 immediately, process in background) optimize database queries add request timeout monitoring check for slow payment provider api calls orders not created in your system solution check webhook endpoint logs for errors verify webhook url is correct in portal test signature verification with sample payload ensure endpoint returns proper json response best practices feed management update frequency daily for most merchants, hourly for high velocity inventory feed size keep under 100mb for faster processing (use pagination if larger) product data include high quality images, detailed descriptions, accurate pricing webhook security always verify signatures — never process unverified webhooks use https — never expose webhook endpoints over http rate limiting — implement rate limiting to prevent abuse idempotency — handle duplicate webhook calls gracefully (use order id as dedup key) error handling retry logic — forter will retry failed webhooks (exponential backoff, up to 3 times) alerting — monitor webhook failure rates logging — log all webhook calls for debugging quick reference supported feed formats google merchant center xml ( feed format "google" ) shopify csv ( feed format "shopify" ) json ( feed format "json" ) webhook authentication method hmac sha256 header {your store name} signature format hmac sha256={hex digest} required webhook response { "success" true, "order id" " ", "order number" " ", "permalink url" " " } next steps docid 6rphy3nxucxydo2hqs4uz — product data synchronization details docid\ km96iibvro23zb4davure — payment processing and order management docid\ g4axxwobilsi4gmhzdnuq — common questions support for custom integration questions, contact your forter representative or email mailto\ support\@forter com