HowSalesDeveloper workspaceAPI reference
HOWSALES / DEVELOPER DOCUMENTATION

Referral API

Connect your website to HowSales product referrals.

Your applications

Start with a tracked product link

The HowSales Referral API records the developer application, marketer, source and campaign behind a product referral. Visits, cart additions, checkouts and verified purchases stay connected to that link.

  1. Create an application using your personal HowSales account and register your HTTPS website.
  2. Store the issued API key and webhook signing secret on your server. These are shown once.
  3. Create a referral link from your server, then use the returned URL on your website.
cURL · server-side request
curl --request POST \
  'https://howsales.net/api/developer-referrals/links' \
  --header "X-HowSales-Api-Key: $HOWSALES_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "productId": "PRODUCT_VERIFY_STRING",
    "source": "website",
    "campaign": "october-launch"
  }'

A successful response uses { "success": true, "data": { ... } }. Use data.url without rebuilding or changing the referral code.

Response · abbreviated
{
  "success": true,
  "data": {
    "code": "SERVER_ISSUED_REFERRAL_CODE",
    "url": "https://howsales.net/api/developer-referrals/visit/SERVER_ISSUED_REFERRAL_CODE",
    "productId": "PRODUCT_VERIFY_STRING",
    "marketerId": "YOUR_USER_ID",
    "sourceSite": "https://your-site.com",
    "source": "website",
    "campaign": "october-launch",
    "commissionEligible": false
  }
}
Ordinary source tracking does not require a commission policy. Commission attribution requires an approved marketer and an active merchant-funded product policy. Public marketers do not need company assignment.

Authentication and credentials

The base path is /api/developer-referrals. Examples use the HowSales website host. The same API is available on the configured API host; generated visitor links use the public website so its checkout receives the attribution cookie.

CredentialUsed for
Personal web session or Bearer tokenRegistering and managing your applications, authorizing a marketer account.
X-HowSales-Api-KeyServer-side link creation, referral reports and webhook operations.
Webhook signing secretVerifying incoming purchase notifications, not authenticating API requests.

The Applications page manages your own integrations through your signed-in session. It does not store API keys in browser storage. Never put developer secrets into public JavaScript, an Android APK, a query string or source control.

Keys are scoped to one application. Rotation invalidates the previous key immediately. Disabling an application stops its API-key access, source links and webhook delivery. Each personal account may register up to ten applications.

Authorize a marketer

Links default to the developer account owner. To use a different marketer ID, that marketer must explicitly authorize your application.

  1. Copy the authorization-page link from your application's Settings tab.
  2. The marketer signs in to HowSales, checks the application name and website, and saves their choice.
  3. Use the returned marketer ID as marketerId in link-creation requests.
Authorization page
https://howsales.net/developers/authorize?client=dev_YOUR_CLIENT_ID

Authorization is separate from company staff membership. It does not expose contacts, private messages, passwords or another developer's reports. The marketer can return to this page, turn off permission, and save to revoke future use and visits.

A registered source website is self-declared application metadata, not proof that every visitor came directly from that domain. Source and campaign labels are reporting metadata, never authorization claims.

Attribution and reports

A visitor link records an open and redirects to the exact HowSales product. A protected first-party cookie retains the source for 30 days. It is bound to the signed-in buyer, or at the first cart addition after an anonymous visit. Web logout clears attribution.

Only the matching product can be attributed. The source is pinned to the real cart line; HowSales advances it at checkout and paid-purchase confirmation. Every visit gets a separate eligible marketer journey, so one buyer's purchase does not consume a reusable developer link.

Visits are raw link opens, not unique people. Bots and repeated opens may increase visits. Cookie removal, another device or an unsupported app handoff can break attribution. Self-referrals are excluded.

Private report
GET /api/developer-referrals/report?offset=0
X-HowSales-Api-Key: YOUR_SERVER_API_KEY

Reports return 50 links per page with visits, cart_count, checkout_count and purchase_count. A purchase is also included in checkout and cart totals. Customer phone numbers, email addresses and private chats are not returned.

API-based clients that manage browser cookies must call POST /clear-attribution when signing out or switching accounts. Automatic native-app/deep-link cookie transfer is not part of this website URL integration.

Purchase webhooks

Set your endpoint in the application's Webhooks tab. It must use HTTPS on port 443 and the exact registered hostname. A public IPv4 address and a valid TLS certificate are required; private addresses and redirects are rejected.

Notifications are sent for referral.purchase_verified. A verified purchase is not a commission payout. Continue using HowSales' commission settlement rules rather than paying from this notification alone.

Webhook payload
{
  "eventId": "evt_123",
  "type": "referral.purchase_verified",
  "occurredUtc": "2026-10-27T10:00:00.0000000Z",
  "referralCode": "SOURCE_LINK_CODE",
  "productId": "PRODUCT_VERIFY_STRING",
  "orderReference": "SHA256_ORDER_REFERENCE",
  "marketerId": "AUTHORIZED_MARKETER_ID",
  "source": "website",
  "campaign": "october-launch",
  "commissionPaid": false
}

Return HTTP 2xx promptly after durably accepting an event. Delivery is at-least-once: save eventId and process it only once. The sender applies a 20-second deadline, leases events, retries with backoff, and stops after eight attempts. Failed events can be requeued in the portal.

Verify the signature

Read the raw request body before JSON parsing. Reject timestamps older than five minutes and compare signatures in constant time.

Signature formula
X-HowSales-Event: evt_123
X-HowSales-Timestamp: UNIX_SECONDS
X-HowSales-Signature: sha256=HEX_HMAC

HEX_HMAC = HMAC-SHA256(
  webhookSecret,
  timestamp + "." + rawRequestBody
)
Node.js · raw body verifier
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyWebhook(rawBody, timestamp, signature, secret) {
  if (!/^\d+$/.test(timestamp || '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(rawBody)
    .digest('hex');
  const received = Buffer.from(signature || '', 'utf8');
  const known = Buffer.from(expected, 'utf8');
  return received.length === known.length &&
    timingSafeEqual(received, known);
}

Endpoint reference

Paths below are relative to /api/developer-referrals. Management endpoints require the signed-in personal account; server endpoints require the API key header.

POST/clients/register

Personal account. Body: name, siteUrl. Returns one-time API and webhook credentials.

POST/clients/list

Personal account. Lists your applications without existing secrets.

POST/clients/settings

Owner only. Body: clientId, enabled, webhookUrl. Send a blank webhook URL to pause delivery.

POST/clients/rotate-key

Owner only. Body: clientId. Returns a replacement API key once and invalidates the previous key.

GET/clients/info/{clientId}

Personal account. Returns application identity and your own authorization state.

POST/clients/authorize

Signed-in marketer. Body: clientId, enabled. Returns your marketer ID and choice.

POST/links

Developer key. Body: productId, optional marketerId, source and campaign.

GET/report?offset=0

Developer key. Returns up to 50 referral links from this application. Increase offset by 50 for the next page. POST is also supported.

GET/webhooks

Developer key. Returns the latest 100 delivery states for this application. POST is also supported.

POST/webhooks/retry/{eventId}

Developer key. Requeues one of this application's failed events.

POST/webhooks/dispatch

Developer key. Processes up to 20 due events belonging to this application.

GET/visit/{code}

Public visitor route. Records an open, sets protected attribution and redirects to the product. Disabled or revoked links are unavailable.

POST/clear-attribution

Clears referral cookies in the current browser session. Use when an API-based client signs out or switches accounts.

Errors and limits

HTTP statusMeaning
400Invalid input, unsupported webhook URL or unavailable product.
401Sign-in required, no ownership/grant, invalid or revoked key, inactive owner, or rate limit.
404Visitor link is unavailable.
500 / 503Temporary server or referral service failure. Retry with backoff.

Developer keys allow up to 120 authenticated requests per minute. Back off after a rate-limit response rather than retrying in a tight loop. Existing commissions may be unavailable while ordinary source links remain usable.

Deployment and delivery operations

Purchase events kick an immediate background dispatch. A timer checks due events every minute while IIS is running. To guarantee retries while an app pool is idle or recycling, schedule a server-side POST to /webhooks/dispatch with that application's key header.

Never put a key in the schedule URL or command logs. Allow enough time for up to 20 delivery attempts per batch. Use the portal's delivery history to inspect attempts and requeue failed events.

For HowSales administrators: publish both web and API projects, set the production PublicSiteBaseUrl, and configure the same explicit ASP.NET machineKey on hosts sharing the database. Database migration rights are needed on first use. Referral.Webhooks.Enabled=false disables automatic workers; explicit authenticated dispatch remains available.

Integration support

When reporting a problem, include your client ID, endpoint path, approximate UTC time and webhook event ID where available. Never send API keys, webhook secrets or customer personal information.

Contact HowSales