Webhooks

FoxCalc delivers real-time event notifications via webhooks. Subscribe to specific event types and receive HMAC-signed payloads at your endpoint.

Event Types

Event	Description
`offer.created`	New offer created
`offer.replaced`	Offer fully replaced (PUT)
`offer.patched`	Offer partially updated (PATCH)
`offer.revoked`	Offer revoked (DELETE)
`offer.expired`	Offer past expiration date
`calculator.opened`	ISO opened the calculator URL
`submission.received`	ISO submitted configured terms
`submission.callback_failed`	Callback delivery to funder failed
`email.bounced`	Notification email bounced
`email.opened`	Notification email opened
`attachment.delivered`	Stipulation attachment delivered
`attachment.delivery_failed`	Attachment delivery failed

Webhook Payload

All webhooks follow the same envelope format:

{
  "event": "submission.received",
  "deal_id": "DEAL-001",
  "funder_id": "funder-uuid",
  "brand_id": "brand-uuid",
  "timestamp": "2026-02-20T15:30:00.000Z",
  "data": {
    "submission": {
      "deal_id": "DEAL-001",
      "purchase_price": 35000,
      "upsell": 0.05,
      "num_payments": 126,
      "selected_frequency": "daily",
      "fee_adjustments": {},
      "computed": {
        "total_factor_rate": 1.25,
        "amount_sold": 43750,
        "commission_rate": 0.05,
        "commission_dollars": 1750,
        "total_fees": 1100,
        "net_to_merchant": 33900,
        "estimated_term_months": 5.81,
        "payment_amount": 347.22
      }
    }
  }
}

Signature Verification

Every webhook includes the same HMAC signature headers used for API requests:

Header	Description
`X-Timestamp`	Unix timestamp
`X-Signature`	HMAC-SHA256 of `timestamp.body` using your webhook secret

Verification Example (Node.js)

import crypto from 'crypto';

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-timestamp'];
  const signature = headers['x-signature'];

  // Reject stale timestamps (> 5 min)
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Submission Callback

When an ISO submits their configured terms, FoxCalc sends the full submission payload to the callback URL configured on the offer (or the brand's default callback URL).

The callback includes:

ISO's selected values (purchase price, upsell, payment count, frequency)
All computed terms (factor rate, amount sold, commission, fees, net to merchant)
Prepayment schedule at submission time
Fee adjustments (if any fees were adjustable)
Attachment references (stipulation file URLs)

Callback Retry Policy

Failed callbacks are retried with exponential backoff:

Attempt 1: Immediate
Attempt 2: 30 seconds
Attempt 3: 2 minutes
Attempt 4: 10 minutes
Attempt 5: 1 hour

After 5 failed attempts, the submission.callback_failed webhook event fires.

Managing Subscriptions

Webhook subscriptions are managed through the Portal UI under Settings > Webhooks. Each subscription specifies:

Target URL
Event types to receive
HMAC secret for signature verification
Active/inactive toggle