API Documentation

How it works

1. Register a webhook endpoint URL in your account
2. Select the events you want to be notified about
3. When an event occurs, we send an HTTP POST request to your URL
4. Your endpoint acknowledges receipt by returning a 2xx status code

Event Payload Example

{
  "event": "alert.triggered",
  "timestamp": "2025-01-01T12:00:00.000Z",
  "data": {
    "alert": {
      "id": "a5d7e3f0-1234-4d8a-9c2b-111111111111",
      "symbol": "AAPL",
      "condition": "price_above",
      "threshold": 200,
      "status": "triggered"
    },
    "stock": {
      "symbol": "AAPL",
      "price": 201.5,
      "change": 2.3,
      "change_percent": 1.15
    }
  }
}

Signature Verification

Every webhook request includes a signature that you should verify to ensure the request came from StockAlert.pro.

X-StockAlert-Signature: a1b2c3d4e5f6...
X-StockAlert-Event: alert.triggered
X-StockAlert-Timestamp: 2024-01-05T10:30:00Z

The signature is the lowercase hex digest of the JSON payload, calculated with HMAC‑SHA256 using your webhook secret.

Verification Examples

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return signature && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

// Express.js example
app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const signature = req.headers['x-stockalert-signature'];
  const payload = req.body;
  
  if (!verifyWebhookSignature(payload, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook...
  res.status(200).send('OK');
});

import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    
    return hmac.compare_digest(signature or '', expected)

# Flask example
@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-StockAlert-Signature')
    payload = request.get_data(as_text=True)
    
    if not verify_webhook_signature(payload, signature, os.environ['WEBHOOK_SECRET']):
        return 'Invalid signature', 401
    
    # Process webhook...
    return 'OK', 200

Best Practices

• ✓Always verify signatures - Never process webhooks without verification
• ✓Use HTTPS endpoints - Webhooks are only sent to secure HTTPS URLs
• ✓Respond quickly - Return a 2xx status within 5 seconds
• ✓Handle retries - Failed webhooks are retried up to 3 times
• ✓Process asynchronously - Queue webhook data for processing to avoid timeouts