Price Alerts API

Overview

The Price Alerts API allows you to set up automated notifications when commodity prices reach your specified thresholds or when advanced analytics conditions are met. Get notified via webhook when prices move.

Features

Standard Price Alerts (Reservoir Mastery)

• Price Targets: Alert when price exceeds or drops below a value
• Condition Operators: greater_than, less_than, equals, not_equals, between
• Webhook Delivery: Real-time HTTP POST to your endpoint
• Cooldown Control: Prevent alert fatigue with configurable cooldowns

Analytics Alerts (Production Boost & Reservoir Mastery)

• Z-Score Alerts: Detect statistical anomalies in price movements
• RSI Alerts: Overbought/oversold signals using Relative Strength Index
• Volatility Spike Alerts: Alert when volatility exceeds historical norms
• Trend Reversal Alerts: Detect momentum changes and trend reversals

Quick Start

Create a Standard Price Alert

curl -X POST https://api.oilpriceapi.com/v1/alerts \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "price_alert": {
      "name": "WTI Above $85",
      "commodity_code": "WTI_USD",
      "condition_operator": "greater_than",
      "condition_value": 85.00,
      "webhook_url": "https://your-app.com/webhooks/price-alerts",
      "cooldown_minutes": 60
    }
  }'

Create an Analytics Alert (Z-Score)

curl -X POST https://api.oilpriceapi.com/v1/alerts \
  -H 'Authorization: Token YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "price_alert": {
      "name": "WTI Statistical Anomaly",
      "commodity_code": "WTI_USD",
      "analytics_type": "z_score",
      "analytics_period": 30,
      "analytics_config": {
        "threshold": 2.5,
        "direction": "both"
      },
      "webhook_url": "https://your-app.com/webhooks/analytics"
    }
  }'

Endpoints

List All Alerts

GET /v1/alerts

Returns all your price alerts ordered by commodity and creation date.

Response:

[
  {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "WTI Above $85",
    "commodity_code": "WTI_USD",
    "condition_operator": "greater_than",
    "condition_value": 85.00,
    "webhook_url": "https://your-app.com/webhook",
    "enabled": true,
    "cooldown_minutes": 60,
    "trigger_count": 3,
    "last_triggered_at": "2025-12-28T10:30:00Z",
    "created_at": "2025-12-15T10:00:00Z"
  },
  {
    "id": "987fcdeb-51a2-3c4d-e567-890123456789",
    "name": "Brent Z-Score Alert",
    "commodity_code": "BRENT_CRUDE_USD",
    "analytics_type": "z_score",
    "analytics_period": 30,
    "analytics_config": { "threshold": 2.0, "direction": "both" },
    "webhook_url": "https://your-app.com/analytics",
    "enabled": true,
    "trigger_count": 1,
    "last_triggered_at": "2025-12-27T14:30:00Z"
  }
]

Create Alert

POST /v1/alerts

Standard Price Alert Parameters

Condition Operators:

• greater_than - Price exceeds value
• less_than - Price drops below value
• equals - Price equals value (within tolerance)
• not_equals - Price differs from value
• between - Price within range (use metadata for min/max)

Analytics Alert Parameters

Get Alert Details

GET /v1/alerts/:id

Returns alert details including trigger history metadata.

Update Alert

PATCH /v1/alerts/:id

Request Body:

{
  "price_alert": {
    "name": "Updated Name",
    "condition_value": 90.00,
    "enabled": false
  }
}

Delete Alert

DELETE /v1/alerts/:id

Returns 204 No Content on success.

Test Alert

POST /v1/alerts/:id/test

Evaluates the alert against the current price and returns whether it would trigger.

Response:

{
  "alert_id": "123e4567-e89b-12d3-a456-426614174000",
  "condition": "WTI_USD greater than 85.0",
  "current_price": {
    "value": 73.45,
    "timestamp": "2025-12-28T14:30:00Z"
  },
  "would_trigger": false,
  "in_cooldown": false,
  "result": "Alert condition not met"
}

Test All Alerts for Commodity

POST /v1/alerts/test?commodity_code=WTI_USD

Evaluates all your alerts for a specific commodity.

Analytics Alerts

Analytics alerts use statistical and technical analysis to detect significant market conditions. These require Production Boost or Reservoir Mastery subscription.

Z-Score Alert

Detects when prices deviate significantly from their historical mean.

Configuration:

{
  "analytics_type": "z_score",
  "analytics_period": 30,
  "analytics_config": {
    "threshold": 2.5,
    "direction": "both"
  }
}

When it triggers: When the current price's z-score exceeds the threshold (e.g., 2.5 standard deviations from mean).

Use case: Detect statistical anomalies for mean-reversion trading strategies.

RSI Alert

Detects overbought or oversold conditions using Relative Strength Index.

Configuration:

{
  "analytics_type": "rsi",
  "analytics_period": 14,
  "analytics_config": {
    "overbought": 70,
    "oversold": 30
  }
}

When it triggers: When RSI crosses above the overbought level or below the oversold level.

Use case: Momentum-based trading signals.

Volatility Spike Alert

Detects when current volatility significantly exceeds historical norms.

Configuration:

{
  "analytics_type": "volatility_spike",
  "analytics_period": 30,
  "analytics_config": {
    "multiplier": 2.0
  }
}

When it triggers: When current volatility exceeds historical average volatility by the multiplier (e.g., 2x normal volatility).

Use case: Risk management, hedging decisions.

Trend Reversal Alert

Detects potential trend changes using momentum analysis.

Configuration:

{
  "analytics_type": "trend_reversal",
  "analytics_period": 20,
  "analytics_config": {}
}

No specific config required. Uses internal momentum and price action analysis.

When it triggers: When momentum indicators suggest a trend reversal is likely.

Use case: Catching trend changes early for position adjustments.

Analytics History

View history of triggered analytics alerts.

GET /v1/alerts/analytics_history

Query Parameters:

• page - Page number (default: 1)
• per_page - Results per page (default: 20, max: 100)

Response:

{
  "triggered_alerts": [
    {
      "id": "987fcdeb-51a2-3c4d-e567-890123456789",
      "name": "WTI Z-Score Alert",
      "commodity_code": "WTI_USD",
      "analytics_type": "z_score",
      "analytics_period": 30,
      "analytics_config": { "threshold": 2.5, "direction": "both" },
      "condition": "WTI_USD z-score exceeds ±2.5 (30-day lookback)",
      "trigger_count": 5,
      "last_triggered_at": "2025-12-28T10:30:00Z",
      "cooldown_minutes": 60,
      "enabled": true,
      "metadata": {
        "z_score": 2.73,
        "mean": 72.50,
        "std_dev": 1.85
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 5
  }
}

Delivery Channels

Analytics alerts support multiple delivery channels. When an alert triggers, notifications are sent based on your configuration and preferences.

Available Channels

Email Notifications

Email notifications are sent automatically when alerts trigger. Emails include:

• Alert type and commodity
• Detailed explanation of the condition
• Current values and thresholds
• Link to manage alerts in dashboard

To disable email notifications, update your notification preferences at /dashboard/settings.

SMS Notifications

SMS notifications are available for Professional, Business, and Enterprise plans. Requirements:

• Verified phone number on account
• SMS notifications enabled in preferences
• Monthly SMS limit not exceeded (10 SMS/month for most plans)

SMS messages are concise and include the key alert information.

Webhook Delivery

When an alert triggers, a webhook is sent to your configured URL (if webhook_url is set).

Standard Alert Webhook Payload

{
  "id": "evt_abc123def456",
  "event": "price_alert.triggered",
  "created_at": "2025-12-28T10:30:00Z",
  "data": {
    "alert_id": "123e4567-e89b-12d3-a456-426614174000",
    "alert_name": "WTI Above $85",
    "commodity_code": "WTI_USD",
    "condition": "greater_than 85.0",
    "current_price": 85.45,
    "threshold": 85.00,
    "triggered_at": "2025-12-28T10:30:00Z"
  }
}

Analytics Alert Webhook Payload

{
  "id": "evt_xyz789ghi012",
  "event": "analytics_alert.triggered",
  "created_at": "2025-12-28T10:30:00Z",
  "data": {
    "alert_id": "987fcdeb-51a2-3c4d-e567-890123456789",
    "alert_name": "WTI Z-Score Alert",
    "commodity_code": "WTI_USD",
    "analytics_type": "z_score",
    "condition": "z-score exceeds ±2.5",
    "current_value": 2.73,
    "threshold": 2.5,
    "details": {
      "z_score": 2.73,
      "mean": 72.50,
      "std_dev": 1.85,
      "current_price": 77.55
    },
    "triggered_at": "2025-12-28T10:30:00Z"
  }
}

Webhook Headers

All webhook requests include:

Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  // Prevent replay attacks (5 minute window)
  if (Date.now() - parseInt(timestamp) * 1000 > 300000) {
    return false;
  }

  const payloadString = JSON.stringify(payload);
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(`${payloadString}.${timestamp}`)
    .digest('hex');

  return signature === expectedSignature;
}

Tier Access

Best Practices

1. Use Appropriate Cooldowns

Prevent alert fatigue by setting reasonable cooldown periods:

{
  "cooldown_minutes": 240
}

For volatile markets, a 4-hour cooldown prevents excessive notifications while still catching significant moves.

2. Combine Multiple Analytics Types

Create complementary alerts for more robust signals:

# Z-Score for statistical anomalies
curl -X POST ... -d '{ "analytics_type": "z_score", "analytics_config": { "threshold": 2.0 }}'

# RSI for momentum confirmation
curl -X POST ... -d '{ "analytics_type": "rsi", "analytics_config": { "overbought": 70, "oversold": 30 }}'

3. Handle Webhooks Idempotently

Always check the event ID to prevent duplicate processing:

app.post('/webhook', (req, res) => {
  const eventId = req.body.id;

  if (processedEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }

  processAlert(req.body);
  processedEvents.add(eventId);

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

4. Test Before Production

Use the test endpoint to validate alert configurations:

POST /v1/alerts/:id/test

Error Codes

Support

• Documentation: docs.oilpriceapi.com/api-reference/alerts
• Email: [email protected]
• Production Boost & Reservoir Mastery: Priority support response within 24 hours