Webhooks & verification

Register an HTTPS URL and we'll POST signed JSON when commission posts or a payout status moves. Create and edit endpoints from the affiliate screen or the API.

Paths below sit under your API root (e.g. https://api.navoswap.com/api/v1/partners/affiliate/webhooks) and need your normal partner JWT.

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).