# integrations

Webhook Integration

Webhooks let you pipe ChainAlert alerts into any system that accepts HTTP requests — PagerDuty, OpsGenie, Telegram bots, Discord channels, your own API, or anything else. Every payload is signed so you can verify it came from ChainAlert.

Setting Up

Go to Channels in the dashboard and create a new channel of type Webhook. Provide:

Endpoint URL — the HTTPS URL that will receive POST requests

Signing secret (optional but recommended) — a secret string used to sign payloads with HMAC-SHA256

Payload Format

Every alert is delivered as an HTTP POST with a JSON body:

webhook — payload example

{
  "alertId": "a1b2c3d4-...",
  "detectionId": "e5f6g7h8-...",
  "detectionName": "Large Transfer Monitor",
  "severity": "high",
  "triggerType": "event-match",
  "network": "ethereum-mainnet",
  "blockNumber": 19500000,
  "transactionHash": "0xef29...12ab",
  "contractAddress": "0xA0b8...eB48",
  "eventName": "Transfer",
  "decodedArgs": {
    "from": "0x3ee1...8a2f",
    "to": "0x7bc4...1d09",
    "value": "5000000000000"
  },
  "timestamp": "2025-03-15T10:30:00Z"
}

Signature Verification

If you configured a signing secret, every request includes two headers for payload verification:

X-ChainAlert-Signature — HMAC-SHA256 hex digest of the raw request body, signed with your secret

X-ChainAlert-Timestamp — Unix timestamp (seconds) when the signature was generated

To verify: compute HMAC-SHA256 of the raw request body using your signing secret, then compare the result to the X-ChainAlert-Signature header. Reject requests where the timestamp is older than 5 minutes to prevent replay attacks.

verification — node.js example

import crypto from "crypto";

function verify(body, secret, signature) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

Retries

If your endpoint returns a non-2xx status code or times out, ChainAlert retries delivery up to 5 times with exponential backoff (starting at 3 seconds). After all retries are exhausted, the alert is marked as "failed" in the dashboard.

Common Use Cases

PagerDuty — point the webhook at a PagerDuty Events API endpoint to create incidents from blockchain alerts

Telegram / Discord — use a lightweight proxy function to reformat the payload and forward to a bot API

Custom automation — trigger runbooks, pause contracts, rotate keys, or log to your SIEM