Receive webhook events

Use them when your backend needs to react without a person sitting in Trade. Typical jobs:

• Credit a lead in your CRM when user.registered arrives.
• Update a trader dashboard when order.filled or contract.settled fires.
• Book revenue when commission.created or payout.completed arrives.

You register URLs in the Partner Dashboard, not through the API. There is no Partner API route to create, list, or rotate endpoints.

1. Enroll as a partner, then open Referrals.
2. Scroll to Webhooks. Enter an HTTPS URL your server can receive (localhost will not work unless you expose it with a public tunnel).
3. Tick the events you actually handle. Start with user.registered, order.filled, and contract.settled if you are unsure.
4. Copy the signing secret immediately. It is shown once at creation. Store it in server env vars, never in a frontend bundle.

Each endpoint only receives the events you selected. If you later need another type, add a new endpoint or recreate this one with the extra events ticked.

Coinpes POSTs JSON. The body is an envelope around the event-specific payload:

{
  "id": "evt_test_preview",
  "type": "order.filled",
  "created_at": "2026-08-30T06:00:00.000Z",
  "data": {
    "userId": 10042,
    "accountId": 3,
    "orderId": 9101,
    "symbol": "R_100",
    "side": "BUY",
    "quantity": "1.00",
    "price": "1234.56"
  }
}

• id — unique event id. Use it as your idempotency key.
• type — the event name, for example order.filled.
• created_at — ISO timestamp.
• data — fields for that event (user id, order id, amounts as strings, and so on).

Headers include Content-Type: application/json, X-Event-Id (same as id), and X-Signature in the form sha256=<hex>. Deliveries time out after 10 seconds. Return 2xx before you do slow work.

• user.registered — a trader signed up through your attribution.
• order.filled, position.opened, position.closed — CFD / Market activity on a referred account.
• contract.placed, contract.settled — timed contracts.
• account.updated — wallet snapshot after a change.
• commission.created, commission.approved, commission.reversed, payout.completed — your partner earnings, not the trader's P/L.

Demo trades still emit trading events if you subscribed, but they never create commission. Filter on account type in data if you only want live activity.

Anyone who discovers your URL can POST JSON at it. Treat the body as untrusted until the signature matches. HMAC-SHA256 the raw body bytes with your signing secret, then compare to the hex after sha256= in constant time.

Read the body as a buffer, not a pre-parsed object — JSON re-serialization changes the bytes and the HMAC will fail.

import crypto from 'node:crypto'

function verifyWebhook(rawBody, secret, signatureHeader) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  const received = signatureHeader.replace(/^sha256=/, '')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
}

Compare the recomputed digest to the header. Reject with 401 if they differ. Then parse JSON and skip events whose id you already stored.

app.post('/webhooks/coinpes', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature']
    if (!verifyWebhook(req.body.toString(), process.env.COINPES_WEBHOOK_SECRET, signature)) {
    return res.sendStatus(401)
  }
  const event = JSON.parse(req.body.toString())
  // handle order.filled, contract.settled, etc.
  res.sendStatus(200)
})

You do not need a referred trader to fill an order before you know the handler works. On each webhook row, choose Test. That opens a modal with:

• An event select — only types this endpoint is subscribed to (for example order.filled).
• A JSON editor prefilled with a sample envelope (id, type, created_at, data). Edit data to match what your handler expects.
• Send test — Coinpes POSTs to your URL with a real HMAC, the same headers as a live event, and a 10 second timeout.

The modal reports delivery status and the HTTP status your server returned. The attempt also appears in that endpoint's delivery log, so you can compare a test against later live events.

Point the URL at a public HTTPS tunnel in development (ngrok, Cloudflare Tunnel, or similar). A test to http://localhost cannot reach your laptop from Coinpes's servers.

Expand a webhook to open its delivery log. You will see status, HTTP code, and attempts. Non-2xx responses and timeouts are retried. After several failed attempts the delivery is marked failed.

Timeouts look like failures even if your process later finished the work. That is why the handler should acknowledge first (2xx) and enqueue the job. If Coinpes retries, your id check must no-op the second time.