Webhooks & verification

Partners can register HTTPS endpoints that receive signed JSON events for affiliate lifecycle updates. Manage endpoints via authenticated partner APIs or the affiliate page in the app.

Supported events

affiliate.commission_accrued: Fired when a new commission ledger entry is created for a completed swap. Payload includes public order_id, amount_usd, and commission_bps.
affiliate.payout_updated: Fired when a payout request’s status changes (e.g. approved, paid).

Management API

GET /partners/affiliate/webhooks: List endpoints.
POST /partners/affiliate/webhooks: Create; a secret is returned once. Store it to verify signatures.
PATCH /partners/affiliate/webhooks/:id: Update URL, events, or active flag.
DELETE /partners/affiliate/webhooks/:id: Remove an endpoint.

Verifying signatures

Webhook delivery & verification

NavoSwap

Build JSON body; sign HMAC-SHA256(secret, timestamp + "." + rawBody)

HTTPS POST

Body: event JSON · Headers: X-NavoSwap-Timestamp, X-NavoSwap-Signature (v1=…)

Your endpoint

Read raw body; recompute HMAC with stored secret; verify v1= hex matches

Response

Return 2xx; run idempotent handler async (ledger, notifications, …)

Compare HMAC in constant time; reject old timestamps to limit replays. Respond 2xx quickly and process work in the background.

Each POST includes:

X-NavoSwap-Timestamp: Unix seconds when the payload was signed.
X-NavoSwap-Signature: Value v1=<hex>; compute HMAC-SHA256(secret, timestamp + "." + rawBody) where rawBody is the exact JSON string posted to your URL.
User-Agent: NavoSwap-Affiliate-Webhooks/1.0

Recompute the HMAC over the same string the server signed (timestamp + "." + rawBody, where rawBody is the exact JSON string), compare in constant time to the v1= value, and reject stale timestamps (replay window) per your security policy.

Audit log

GET /partners/affiliate/audit exposes partner-visible audit entries for affiliate actions (paginated).