Documentation

Webhooks

Receive real-time HTTP notifications when events occur on your LP position — fills, withdrawals, and activation changes.

Webhooks are on the roadmap. Configure your endpoint URL now in Settings to be ready.

Last updated: 8 April 2026

Overview

When an event occurs, SimpleFX sends an HTTP POST request to your configured webhook URL with a JSON body describing the event. Your endpoint must respond with a 2xx status code within 10 seconds to acknowledge receipt.

Failed deliveries are retried up to 5 times with exponential backoff (1s, 5s, 30s, 2min, 10min). After 5 failures the event is marked as undelivered and logged in your dashboard.

Webhook request headers

X-SimpleFX-Event	Event type, e.g. fill.completed
X-SimpleFX-Signature	HMAC-SHA256 signature of the raw body using your webhook secret
X-SimpleFX-Timestamp	Unix timestamp (seconds) of the delivery attempt
Content-Type	application/json

Signature Verification

Always verify the X-SimpleFX-Signature header before processing an event. This prevents attackers from spoofing webhook payloads.

Verification — Node.jstypescript

import { createHmac } from 'crypto'

function verifyWebhook(
  rawBody: string,
  signature: string,
  secret: string,
): boolean {
  const expected = createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  return `sha256=${expected}` === signature
}

Event Reference

fill.completedFired when a swap fills against your inventory

Payloadjson

{
  "event": "fill.completed",
  "lpId": "lp_01jqe...",
  "data": {
    "fillId": "fill_01jqe...",
    "fromToken": "USDC",
    "toToken": "NTZS",
    "amountIn": "10.000000",
    "amountOut": "37312.500000000000000000",
    "feesEarned": "37.312500000000000000",
    "inTxHash": "0xabc...",
    "outTxHash": "0xdef...",
    "timestamp": "2026-04-08T09:28:00Z"
  }
}

fill.failedFired when a swap could not be filled (e.g. insufficient liquidity)

Payloadjson

{
  "event": "fill.failed",
  "lpId": "lp_01jqe...",
  "data": {
    "fromToken": "USDC",
    "toToken": "NTZS",
    "amountIn": "10.000000",
    "reason": "INSUFFICIENT_LIQUIDITY",
    "timestamp": "2026-04-08T09:29:00Z"
  }
}

position.activatedposition.deactivated

Payloadjson

{
  "event": "position.activated",
  "lpId": "lp_01jqe...",
  "data": {
    "walletAddress": "0x723A3D...155aBe",
    "timestamp": "2026-04-08T09:30:00Z"
  }
}

withdrawal.confirmedFired when a withdrawal transaction is confirmed on-chain

Payloadjson

{
  "event": "withdrawal.confirmed",
  "lpId": "lp_01jqe...",
  "data": {
    "token": "ntzs",
    "amount": "500.000000000000000000",
    "toAddress": "0xRecipient...",
    "txHash": "0xghi...",
    "timestamp": "2026-04-08T09:35:00Z"
  }
}

Configure Your Endpoint

Go to SimpleFX Dashboard → Settings → Webhooks and enter your HTTPS endpoint URL. A webhook secret will be generated — store it securely as your signing key for signature verification.

Your endpoint must be publicly reachable over HTTPS. Self-signed certificates are not accepted. For local development, use a tunneling service such as ngrok or cloudflared.

Checklist

Endpoint is reachable via HTTPS with a valid certificate
Returns 200 within 10 seconds
Verifies the X-SimpleFX-Signature header before processing
Handles duplicate deliveries idempotently (use fillId as dedup key)