🔗

Webhooks Guide

Receive real-time notifications when events occur in your DeFi Guardian account. Webhooks push data to your server instantly, enabling automated workflows.

● How Webhooks Work

Event Occurs

An event happens in your account (e.g., health factor drops below threshold)

Payload Sent

DeFi Guardian sends a POST request to your configured endpoint

Your Server Responds

Your server processes the event and returns a 2xx response

Delivery Guarantees: We attempt delivery up to 5 times with exponential backoff. Failed deliveries are logged and can be retried manually from your dashboard.

● Setting Up a Webhook

1
Go to Developer Portal → Webhooks
Navigate to your dashboard and click on the Developer section.
2
Click "Add Webhook"
Enter your endpoint URL (must be HTTPS in production).
3
Select Events
Choose which events should trigger this webhook.
4
Copy Your Secret
Save the webhook secret securely - you'll need it to verify signatures.

● Event Types

alert.created

Triggered when a new alert is generated based on your rules

{ "alertType": "warning", "severity": 6, "title": "Low Health Factor", "position": { "healthFactor": 1.35, "protocol": "aave_v3" } }

alert.resolved

Triggered when an alert condition is no longer met

{ "alertType": "safe", "title": "Health Factor Recovered", "position": { "healthFactor": 2.10, "protocol": "aave_v3" } }

position.updated

Triggered when position data changes

{ "positionId": "...", "healthFactor": 1.45, "previousHealthFactor": 1.52, "totalCollateralUsd": 15200, "protocol": "aave_v3", "chainId": 42161 }

position.liquidation_risk

Triggered when a position enters liquidation risk zone (health factor below threshold)

{ "positionId": "...", "healthFactor": 1.08, "protocol": "aave_v3", "chainId": 1, "riskLevel": "critical" }

test.ping

Sent when you click Send Test in the developer portal or call POST /v1/webhooks/:id/test

{ "message": "Webhook test from DeFi Guardian API", "webhookId": "...", "timestamp": "2026-03-21T12:00:00Z" }

● Payload Format

All webhook payloads follow this structure:

Webhook Payload

{
  "event": "alert.created",
  "timestamp": "2026-03-22T10:30:00Z",
  "webhookId": "bba53181-93de-41ac-b1c8-0b03fab01fc6",
  "data": {
    "alertType": "warning",
    "severity": 6,
    "title": "Low Health Factor",
    "message": "Health factor dropped to 1.35",
    "position": {
      "id": "644c56a1-06d9-4787-9b8b-a0ba28f42338",
      "healthFactor": 1.35,
      "collateralUsd": 15200.50,
      "debtUsd": 11260.00,
      "protocol": "aave_v3",
      "chainId": 42161
    },
    "confidenceScore": 0.92
  }
}

● Verifying Signatures

Every webhook request includes a signature header that you should verify to ensure authenticity.

⚠️ Security Best Practice

Always verify webhook signatures in production to prevent spoofed requests.

Node.js Example

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex')
  );
}

// In your Express handler:
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-defi-guardian-signature'];
  const event = req.headers['x-defi-guardian-event'];
  const deliveryId = req.headers['x-defi-guardian-delivery'];

  const isValid = verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(400).send('Invalid signature');
  }

  // Process the webhook...
  const payload = JSON.parse(req.body);
  console.log('Received:', event, payload.data);

  res.status(200).send('OK');
});

Python Example

import hmac
import hashlib

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

# In your Flask handler:
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-DeFi-Guardian-Signature')
    is_valid = verify_webhook_signature(
        request.data,
        signature,
        os.environ['WEBHOOK_SECRET']
    )
    
    if not is_valid:
        return 'Invalid signature', 400
    
    payload = request.json
    print(f"Received: {payload['event']} for webhook {payload['webhookId']}")

    return 'OK', 200

● Retry Policy

If your endpoint returns a non-2xx status code or times out, we'll retry with exponential backoff:

Attempt	Wait Time	Cumulative
1	Immediate	0s
2	1 minute	1m
3	5 minutes	6m
4	30 minutes	36m
5	2 hours	~2.5h

After 5 failed attempts, the webhook is marked as failed. You can manually retry from Dashboard → Developer → Delivery Logs.

● Best Practices

⚡

Respond Quickly

Return a 200 response within 10 seconds. Process the event asynchronously if needed.

🔒

Verify Signatures

Always validate the X-DeFi-Guardian-Signature header to ensure requests are from DeFi Guardian.

🔄

Handle Duplicates

Use the event ID to deduplicate. We may occasionally send the same event twice.

📝

Log Everything

Log all incoming webhooks for debugging. Include event ID, type, and timestamp.

🌐

Use HTTPS

We only deliver webhooks to HTTPS endpoints in production for security.

🔔

Monitor Failures

Set up alerts if your webhook endpoint starts returning errors.

● Testing Webhooks

Use these tools to test your webhook endpoint before going live:

webhook.site

Free service to inspect incoming webhooks

ngrok

Expose localhost to the internet for testing

Postman

Simulate webhook requests locally