Webhooks

Overview

Lavarage supports outbound webhooks so your server receives push notifications when position state changes, rather than polling the API.

To enable webhooks, configure webhookUrl and webhookSecret on your partner profile. Only HTTPS endpoints are accepted.

Event Types

Event	Trigger
`position.opened`	Position opened on-chain and indexed
`position.closed`	Position fully closed
`position.liquidated`	Position was liquidated
`order.executed`	TP/SL order executed successfully
`order.failed`	TP/SL order execution failed
`ltv.warning`	Position LTV approaching liquidation threshold

Payload Shape

{
  "type": "position.closed",
  "positionAddress": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "walletAddress": "GsbwXfJraMomNxBcjK7xK2xQx5MQgQx4Ld8QkLeNmA3v",
  "data": {},
  "timestamp": "2026-03-15T12:00:00.000Z"
}

Verifying the Signature

Every delivery includes two headers:

X-Lavarage-Signature: HMAC-SHA256 hex digest
X-Lavarage-Timestamp: ISO timestamp

The signed content is ${timestamp}.${JSON.stringify(payload)}.

import { createHmac } from 'crypto'

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

// Express example
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const valid = verifyWebhook(
    req.body.toString(),
    req.headers['x-lavarage-signature'] as string,
    req.headers['x-lavarage-timestamp'] as string,
    process.env.WEBHOOK_SECRET!,
  )
  if (!valid) return res.status(401).send('Invalid signature')

  const event = JSON.parse(req.body.toString())
  console.log('Event received:', event.type, event.positionAddress)
  res.status(200).send('OK')
})

Delivery Guarantees

Webhook delivery has a 10-second timeout
Delivery is fire-and-forget — failed deliveries are not retried
Ensure your endpoint responds with HTTP 2xx within 10 seconds
Webhooks are only delivered if your partner profile has both webhookUrl and webhookSecret configured and webhookEnabled is true