Skip to main content

API Documentation

Everything you need to integrate StockAlert.pro into your applications

Webhooks

Receive real-time HTTP notifications when events occur in your account

Overview

Webhooks allow your application to receive real-time notifications when certain events occur in your StockAlert.pro account. Instead of polling the API for changes, webhooks push data to your endpoint as soon as an event happens.

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

Tip: You can have up to 5 webhook endpoints per account, allowing you to send different events to different services.

Webhook Events

EventDescriptionStatus
alert.triggeredAlert condition has been met and notification sentAvailable
alert.createdNew alert created via API or dashboardComing Soon
alert.updatedAlert settings changed (paused/reactivated)Coming Soon
alert.deletedAlert permanently removedComing Soon

Note: Additional events will be added based on user demand. Let us know which events you'd like to see!

Event Payload Example

{
  "id": "evt_1234567890",
  "type": "alert.triggered",
  "created": "2024-01-05T10:30:00Z",
  "data": {
    "alert": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "symbol": "AAPL",
      "company_name": "Apple Inc.",
      "condition": "price_above",
      "threshold": 200,
      "triggered_value": 201.50,
      "notification": "email",
      "created_at": "2024-01-01T00:00:00Z",
      "triggered_at": "2024-01-05T10:30:00Z"
    },
    "user": {
      "id": "user_123",
      "email": "user@example.com"
    }
  }
}

Webhook Endpoints

List Webhooks

GET/api/public/v1/webhooks

Get a list of all configured webhooks.

Example Response
{
  "success": true,
  "data": [
    {
      "id": "wh_1234567890",
      "url": "https://your-app.com/webhook",
      "events": ["alert.triggered"],
      "is_active": true,
      "created_at": "2024-01-01T00:00:00Z",
      "last_success": "2024-01-05T10:00:00Z",
      "last_failure": null
    }
  ]
}

Create Webhook

POST/api/public/v1/webhooks

Register a new webhook endpoint.

Request Body
{
  "url": "https://your-app.com/webhook",
  "events": ["alert.triggered"]  // Currently the only available event
}
Parameters
  • url - The HTTPS endpoint that will receive webhook events
  • events - Array of event types to subscribe to

Delete Webhook

DELETE/api/public/v1/webhooks/{id}

Remove a webhook endpoint.

Example Request
curl -X DELETE https://stockalert.pro/api/public/v1/webhooks/wh_1234567890 \
  -H "X-API-Key: sk_your_api_key"

Webhook Security

Signature Verification

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

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

The signature is calculated using HMAC-SHA256 with your webhook secret (found in your dashboard).

Verification Examples

Node.js / JavaScript
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  return signature === 'sha256=' + 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');
});
Python
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 signature == f'sha256={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

Testing Webhooks

During development, you can use services like ngrok or webhook.site to test webhook deliveries:

Using ngrok

# 1. Start your local server
npm run dev  # Runs on http://localhost:3000

# 2. Expose it with ngrok
ngrok http 3000

# 3. Use the HTTPS URL from ngrok as your webhook endpoint
https://abc123.ngrok.io/api/webhook

Note: Webhook endpoints must use HTTPS. HTTP URLs will be rejected for security reasons.