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.
- Create an application using your personal HowSales account and register your HTTPS website.
- Store the issued API key and webhook signing secret on your server. These are shown once.
- Create a referral link from your server, then use the returned URL on your website.
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.
{
"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
}
}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.
| Credential | Used for |
|---|---|
| Personal web session or Bearer token | Registering and managing your applications, authorizing a marketer account. |
X-HowSales-Api-Key | Server-side link creation, referral reports and webhook operations. |
| Webhook signing secret | Verifying 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.
Create and share links
| Field | Rules |
|---|---|
productId | Required. Product verify string from HowSales. The server resolves its company. |
marketerId | Optional. Defaults to the client owner. Another account must grant permission first. |
source | Optional label, up to 100 characters. |
campaign | Optional label, up to 100 characters. |
Node.js
const response = await fetch(
'https://howsales.net/api/developer-referrals/links',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-HowSales-Api-Key': process.env.HOWSALES_API_KEY
},
body: JSON.stringify({
productId: 'PRODUCT_VERIFY_STRING',
source: 'website',
campaign: 'october-launch'
})
}
);
const result = await response.json();
if (!response.ok || !result.success) {
throw new Error(result.message || 'Referral creation failed');
}
const referralUrl = result.data.url;Display the returned URL as a product link. Do not call this secret-key endpoint directly from a visitor's browser. The Applications page also provides a link builder for your own account.
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.
GET /api/developer-referrals/report?offset=0
X-HowSales-Api-Key: YOUR_SERVER_API_KEYReports 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.
{
"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.
X-HowSales-Event: evt_123
X-HowSales-Timestamp: UNIX_SECONDS
X-HowSales-Signature: sha256=HEX_HMAC
HEX_HMAC = HMAC-SHA256(
webhookSecret,
timestamp + "." + rawRequestBody
)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 status | Meaning |
|---|---|
| 400 | Invalid input, unsupported webhook URL or unavailable product. |
| 401 | Sign-in required, no ownership/grant, invalid or revoked key, inactive owner, or rate limit. |
| 404 | Visitor link is unavailable. |
| 500 / 503 | Temporary 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