Webhooks & Alerting

Webhooks and alerting let you receive notifications when important events happen in your Barfinex stack — signals, AI decisions, risk actions, service outages, and more.

Webhooks

Creating a webhook

1. Open Studio → Webhooks.
2. Click Create Webhook.
3. Fill in the configuration:

4. Click Save. Studio will send a test ping to verify the URL is reachable.

Available event types

Payload format

Each webhook delivery is an HTTP POST with a JSON body:

{
  "id": "evt_abc123",
  "type": "signal.emitted",
  "timestamp": "2026-03-27T12:00:00.000Z",
  "data": {
    "symbol": "BTCUSDT",
    "direction": "LONG",
    "score": 0.82
  }
}

The data field varies by event type.

HMAC signature verification

If you configure a Secret on the webhook, every delivery includes an X-Barfinex-Signature header containing an HMAC-SHA256 signature of the request body.

To verify:

1. Compute HMAC-SHA256(secret, raw_request_body).
2. Compare the result with the value in X-Barfinex-Signature.
3. If they match, the payload is authentic and unmodified.

Example (Node.js):

const crypto = require('crypto');

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

Delivery and retries

• Studio delivers webhooks with a 10-second timeout.
• If the endpoint returns a non-2xx status, Studio retries up to 3 times with exponential backoff (10s, 30s, 90s).
• Failed deliveries are visible in the webhook's delivery history.
• You can manually retry a failed delivery from the Studio UI.

Alerting

Alert rule types

Creating an alert rule

1. Open Studio → Alerting.
2. Click Create Rule.
3. Select the rule type and configure parameters:
   • For No signals: select the strategy and the silence threshold (minutes).
   • For Drawdown threshold: set the percentage threshold.
   • For Service down: select the service and the unreachable threshold (seconds).
4. Under Delivery, select one or more webhooks to receive the alert notification.
5. Click Save.

Connecting alerts to webhooks

Alert rules do not deliver notifications on their own. Each rule must be connected to at least one webhook.

When the alert condition is met:

1. Studio evaluates the rule.
2. If triggered, Studio sends a webhook delivery with event type alert.triggered.
3. The payload includes the rule type, threshold, and current value.

Example alert payload:

{
  "id": "evt_def456",
  "type": "alert.triggered",
  "timestamp": "2026-03-27T12:05:00.000Z",
  "data": {
    "rule": "drawdown_threshold",
    "threshold": 5.0,
    "current_value": 5.3,
    "message": "Portfolio drawdown exceeded 5.0% (current: 5.3%)"
  }
}

Delivery channels

Webhooks can point to any HTTP endpoint, so you can deliver alerts to:

• Slack — use a Slack Incoming Webhook URL.
• Telegram — use a Telegram Bot API URL with your chat ID.
• PagerDuty — use the PagerDuty Events API v2 endpoint.
• Custom services — any HTTPS endpoint that accepts POST requests.

Troubleshooting