OpsionDocs
ConsoleWebsiteSign in

Webhooks

Webhooks let you receive real-time HTTP POST requests to your own endpoint every time an alert rule fires. This is useful for integrating Opsion into your own dashboards, incident workflows, or compliance systems.

Setup

bash
curl -X POST https://api.opsion.xyz/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-service.example.com/opsion-webhook",
    "events": ["alert.fired"],
    "secret": "wh_secret_xxxxxxxxxxxxx"
  }'

Payload shape

json
{
  "event": "alert.fired",
  "fired_at": "2025-03-21T14:23:01Z",
  "rule": {
    "id": "rul_01j9xmk4p8q3r7t2",
    "name": "Large ETH outflow"
  },
  "transaction": {
    "hash": "0xabc123…",
    "chain": "ethereum",
    "from": "0xd8dA6BF…",
    "to": "0xA0b869…",
    "value_eth": "12.5",
    "value_usd": "37500.00",
    "block": 21843200,
    "timestamp": "2025-03-21T14:22:59Z"
  }
}

Verifying signatures

Every webhook request includes an X-Opsion-Signature header containing an HMAC-SHA256 signature of the raw request body, signed with your webhook secret.

typescript
import { createHmac } from 'crypto'

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

Retries

Opsion retries failed deliveries (non-2xx or timeout) up to 5 times with exponential backoff: 5s, 30s, 2m, 10m, 1h. After 5 failures the delivery is marked as failed and can be manually replayed from the console.

AlertsRate Limits