Custom Webhook Alert Setup

Webhooks let you receive ChainRaven alerts directly at your own HTTP endpoint. Use them to forward alerts to Slack or PagerDuty, store events in your own database, trigger custom workflows, or integrate with any system.

What You'll Need

• A publicly accessible HTTP(S) endpoint
• Your endpoint must respond within 10 seconds

Tip: Use webhook.site to get an instant test URL and inspect exactly what ChainRaven sends before writing any code.

Step 1: Create Your Endpoint

Your endpoint must:

1. Accept POST requests with a JSON body
2. Return a 200 status code on success
3. Respond within 10 seconds (otherwise ChainRaven marks the delivery as failed and retries)

Minimal Node.js example:

const express = require('express')
const app = express()

app.use(express.json())

app.post('/chainraven-webhook', (req, res) => {
  console.log('Alert received:', req.body)
  res.status(200).send('OK')
})

app.listen(3000)

Step 2: Configure in ChainRaven

Webhooks are configured per alert type, so you can route different alerts to different endpoints.

1. Go to Profile > Alert Preferences
2. Expand the alert type you want to configure (e.g., Large Transfer)
3. Check the Webhook checkbox
4. Enter your Webhook URL
5. Optionally enter a Webhook Secret for signature verification
6. Click Save Changes

Repeat for each alert type you want to route via webhook.

Step 3: Test Your Webhook

1. Get a free test URL at webhook.site
2. Paste it as your webhook URL in ChainRaven's Alert Preferences
3. Trigger a test alert or wait for the next real event
4. Check webhook.site to inspect the full request payload

Payload Format

ChainRaven sends POST requests with this structure:

Headers:

Content-Type: application/json
X-ChainRaven-Timestamp: 2026-01-05T10:30:00.000Z
X-ChainRaven-Signature: <hmac-sha256-hex>  (if secret configured)

Body:

{
  "event": "alert.sent",
  "timestamp": "2026-01-05T10:30:00.000Z",
  "data": {
    "alertType": "OWNERSHIP_TRANSFER",
    "severity": "critical",
    "contractAddress": "0x1234...",
    "chain": "ethereum",
    "eventData": {
      "previousOwner": "0xaaaa...",
      "newOwner": "0xbbbb..."
    },
    "transactionHash": "0xabcdef...",
    "blockNumber": 12345678,
    "detectedAt": "2026-01-05T10:30:00.000Z",
    "dashboardUrl": "https://chainraven.io/dashboard"
  }
}

The eventData field varies by alert type:

Signature Verification (Optional)

If you configure a webhook secret, ChainRaven includes an HMAC-SHA256 signature in the X-ChainRaven-Signature header. Verify it to confirm requests actually came from ChainRaven and weren't tampered with.

Node.js verification example:

const crypto = require('crypto')

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex')

  return signature === expected
}

// In your endpoint:
const signature = req.headers['x-chainraven-signature']
if (signature && !verifySignature(req.body, signature, 'your-secret')) {
  return res.status(401).send('Invalid signature')
}

Troubleshooting

Not receiving webhooks?

1. Verify the webhook URL is correct and publicly accessible from the internet
2. Make sure the Webhook checkbox is enabled for the alert type in Alert Preferences
3. Check that your server is running and accepting POST requests
4. Look at Sent Alerts in your dashboard to see if delivery was attempted and what the response was

Signature verification failing?

1. Confirm the secret in your code exactly matches what you entered in ChainRaven (case-sensitive)
2. Verify the signature against the raw JSON body — do not parse or modify it before verification
3. Ensure you're using HMAC-SHA256 (not MD5 or SHA-1)

Receiving duplicate alerts?

Due to automatic retries, you may receive the same alert more than once. Deduplicate by tracking processed transaction hashes:

const processed = new Set()

app.post('/webhook', (req, res) => {
  const id = req.body.data.transactionHash
  if (processed.has(id)) {
    return res.status(200).send('Already processed')
  }
  processed.add(id)
  // Process the alert...
  res.status(200).send('OK')
})

Tips

• Respond quickly — return 200 immediately if you need to do heavy processing, then handle it asynchronously in the background
• Use HTTPS — always use HTTPS endpoints; HTTP webhooks may be rejected in the future
• Configure a secret — adds a layer of verification that requests came from ChainRaven
• Log all incoming requests — logging helps debug missed or malformed deliveries

Next Steps

• Alert Preferences — Customize when you get notified and configure per-type webhook URLs
• Understanding Alerts — Learn about each alert type and their eventData fields