Market.ai Webhooks Guide

Push market signal notifications to Discord, Slack, Telegram, or any custom HTTP endpoint. Configure filters to receive only the signals that matter to you, with automatic retry on delivery failure.

Overview

When Market.ai detects a market signal (whale movement, liquidation cascade, funding spike, etc.), it can automatically push a notification to your configured endpoints. You define:

Where to send notifications (URL + platform)
What signals to send (filters on type, severity, symbol, exchange)
How to format them (Discord embed, Slack Block Kit, Telegram Markdown, or raw JSON)

Webhooks are available on all tiers.

Quick Start

Get your Discord webhook URL (or Slack/Telegram/custom endpoint)
Register it with Market.ai:

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://discord.com/api/webhooks/123456/abcdef",
    "platform": "discord",
    "name": "BTC Critical Alerts",
    "filters": {
      "severities": ["alert", "critical"],
      "symbols": ["BTC/USDT"]
    }
  }' \
  https://api.market-ai.dev/v1/webhooks

You will now receive Discord notifications whenever an alert or critical signal fires for BTC/USDT.

API Endpoints

All webhook endpoints require authentication.

Register a Webhook

POST/v1/webhooks

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://discord.com/api/webhooks/123456/abcdef",
    "platform": "discord",
    "name": "My Alerts",
    "filters": {
      "signalTypes": ["whale_movement", "liquidation_cascade"],
      "severities": ["alert", "critical"],
      "symbols": ["BTC/USDT", "ETH/USDT"],
      "exchanges": ["binance", "bybit"]
    },
    "authHeader": "Bearer my-secret-token"
  }' \
  https://api.market-ai.dev/v1/webhooks

Request body:

Field	Type	Required	Description
`url`	string	Yes	Destination URL for HTTP POST delivery
`platform`	string	Yes	`discord`, `slack`, `telegram`, or `custom`
`name`	string	No	Human-readable label (max 100 chars)
`filters`	object	No	Signal matching filters (empty = match all)
`authHeader`	string	No	Optional `Authorization` header value for custom webhooks

Response (201 Created):

{
  "ok": true,
  "data": {
    "id": "wh_abc123",
    "userId": "...",
    "url": "https://discord.com/api/webhooks/123456/abcdef",
    "platform": "discord",
    "name": "My Alerts",
    "filters": {
      "signalTypes": ["whale_movement", "liquidation_cascade"],
      "severities": ["alert", "critical"],
      "symbols": ["BTC/USDT", "ETH/USDT"],
      "exchanges": ["binance", "bybit"]
    },
    "active": true,
    "createdAt": 1708776300000,
    "updatedAt": 1708776300000
  },
  "meta": { "timestamp": 1708776300000 }
}

List Webhooks

GET/v1/webhooks

Returns all webhooks owned by the authenticated user.

curl -H "Authorization: Bearer mk_live_abc123..." \
  https://api.market-ai.dev/v1/webhooks

Response:

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "wh_abc123",
        "url": "https://discord.com/api/webhooks/...",
        "platform": "discord",
        "name": "BTC Critical Alerts",
        "filters": { ... },
        "active": true,
        "createdAt": 1708776300000,
        "updatedAt": 1708776300000
      }
    ],
    "total": 2
  },
  "meta": { "timestamp": 1708776300000 }
}

Get a Webhook

GET/v1/webhooks/:id

curl -H "Authorization: Bearer mk_live_abc123..." \
  https://api.market-ai.dev/v1/webhooks/wh_abc123

Update a Webhook

PATCH/v1/webhooks/:id

Update any combination of fields. Only the provided fields are changed.

curl -X PATCH -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "severities": ["critical"]
    },
    "active": false
  }' \
  https://api.market-ai.dev/v1/webhooks/wh_abc123

Updatable fields:

Field	Type	Description
`url`	string	Destination URL
`name`	string	Human-readable label
`filters`	object	Signal matching filters
`active`	boolean	Enable/disable the webhook
`authHeader`	string	Authorization header value

Delete a Webhook

DELETE/v1/webhooks/:id

Returns 204 No Content on success.

curl -X DELETE -H "Authorization: Bearer mk_live_abc123..." \
  https://api.market-ai.dev/v1/webhooks/wh_abc123

View Delivery Log

GET/v1/webhooks/:id/deliveries

Get the delivery history for a webhook. Useful for debugging failed deliveries.

Parameter	Type	Default	Description
`limit`	integer	20	Results per page (1-100)
`offset`	integer	0	Results to skip

curl -H "Authorization: Bearer mk_live_abc123..." \
  "https://api.market-ai.dev/v1/webhooks/wh_abc123/deliveries?limit=10"

Response:

{
  "ok": true,
  "data": {
    "items": [
      {
        "id": "del_xyz789",
        "webhookId": "wh_abc123",
        "signalId": "sig_def456",
        "status": "delivered",
        "attempts": 1,
        "lastAttemptAt": 1708776300000,
        "deliveredAt": 1708776300500,
        "createdAt": 1708776300000
      },
      {
        "id": "del_abc111",
        "webhookId": "wh_abc123",
        "signalId": "sig_ghi789",
        "status": "failed",
        "attempts": 3,
        "lastAttemptAt": 1708776400000,
        "error": "HTTP 503: Service Unavailable",
        "createdAt": 1708776300000
      }
    ],
    "total": 45,
    "limit": 10,
    "offset": 0
  },
  "meta": { "timestamp": 1708776500000 }
}

Delivery statuses:

Status	Description
`pending`	Delivery queued, not yet attempted
`delivered`	Successfully delivered (2xx HTTP response)
`failed`	All retry attempts exhausted

Filter Configuration

Filters determine which signals trigger a webhook. If a filter field is omitted, it matches all values for that field. All filter fields use AND logic (a signal must match all specified filters).

{
  "filters": {
    "signalTypes": ["whale_movement", "liquidation_cascade"],
    "severities": ["alert", "critical"],
    "symbols": ["BTC/USDT", "ETH/USDT"],
    "exchanges": ["binance", "bybit"]
  }
}

Field	Type	Description
`signalTypes`	string[]	Match only these signal types
`severities`	string[]	Match only these severity levels
`symbols`	string[]	Match only these trading pairs
`exchanges`	string[]	Match only signals from these exchanges

Available signal types:

whale_movement -- Single trade exceeding $500K
liquidation_cascade -- Over $1M in liquidations within 5 minutes
funding_spike -- Funding rate exceeds +/-0.05%
orderbook_imbalance -- OBI exceeds +/-0.3
spread_anomaly -- Spread exceeds 3x average
volume_spike -- 5-minute volume exceeds 5x average
cross_exchange_divergence -- Price divergence exceeds 50 bps
wall_appearance -- New orderbook wall exceeding 10x median
wall_removal -- Tracked wall disappears
price_level_break -- Support or resistance level broken

Examples:

Receive only critical signals for any symbol:

{ "filters": { "severities": ["critical"] } }

Receive all signal types for BTC only:

{ "filters": { "symbols": ["BTC/USDT"] } }

Receive whale movements and liquidation cascades across all symbols (no other filters):

{ "filters": { "signalTypes": ["whale_movement", "liquidation_cascade"] } }

Receive everything (empty filters):

{ "filters": {} }

Platform Setup

Discord

In your Discord server, go to Server Settings > Integrations > Webhooks
Click "New Webhook", name it, choose a channel, and copy the webhook URL
Register the webhook with platform: "discord" and your Discord webhook URL

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://discord.com/api/webhooks/123456789/abcdefghijklmnop",
    "platform": "discord",
    "name": "Market Alerts"
  }' \
  https://api.market-ai.dev/v1/webhooks

Discord notifications appear as embedded messages with color-coded severity (gray for info, yellow for warning, orange for alert, red for critical).

Slack

Create a Slack app at api.slack.com
Enable Incoming Webhooks and add one to your channel
Copy the webhook URL
Register with platform: "slack"

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "platform": "slack",
    "name": "Market Alerts"
  }' \
  https://api.market-ai.dev/v1/webhooks

Slack notifications use Block Kit formatting with structured fields for symbol, exchange, severity, and signal type.

Create a bot via @BotFather and get the bot token
Find your chat ID (send a message to the bot, then check https://api.telegram.org/bot<TOKEN>/getUpdates)
Use the Telegram Bot API sendMessage URL as the webhook URL
Register with platform: "telegram"

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.telegram.org/bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11/sendMessage?chat_id=-1001234567890",
    "platform": "telegram",
    "name": "Market Alerts"
  }' \
  https://api.market-ai.dev/v1/webhooks

Telegram notifications use Markdown formatting with bold headers and structured signal details.

Custom HTTP

For custom endpoints, Market.ai sends a raw JSON POST with the standard webhook payload. Optionally include an authHeader value that will be sent as the Authorization header on each request.

curl -X POST -H "Authorization: Bearer mk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://my-app.com/webhooks/market-signals",
    "platform": "custom",
    "name": "My App Integration",
    "authHeader": "Bearer my-webhook-secret-token"
  }' \
  https://api.market-ai.dev/v1/webhooks

Payload Formats

Custom (Raw JSON)

{
  "event": "signal",
  "signal": {
    "id": "sig_abc123",
    "type": "whale_movement",
    "severity": "alert",
    "symbol": "BTC/USDT",
    "exchange": "binance",
    "narrative": "Whale buy detected on Binance: $2.5M BTC market order absorbed in 3 seconds",
    "data": {
      "exchange": "binance",
      "size_usd": 2500000,
      "side": "buy"
    },
    "timestamp": 1708776300000
  },
  "delivered_at": 1708776300500
}

Discord (Embed)

{
  "embeds": [
    {
      "title": "WHALE MOVEMENT",
      "description": "Whale buy detected on Binance: $2.5M BTC market order absorbed in 3 seconds",
      "color": 15105570,
      "fields": [
        { "name": "Symbol", "value": "BTC/USDT", "inline": true },
        { "name": "Exchange", "value": "binance", "inline": true },
        { "name": "Severity", "value": "alert", "inline": true }
      ],
      "timestamp": "2024-02-24T12:05:00.000Z",
      "footer": { "text": "Market.ai Signal Alert" }
    }
  ]
}

Slack (Block Kit)

{
  "blocks": [
    {
      "type": "header",
      "text": { "type": "plain_text", "text": "WHALE MOVEMENT" }
    },
    {
      "type": "section",
      "fields": [
        { "type": "mrkdwn", "text": "*Symbol:*\nBTC/USDT" },
        { "type": "mrkdwn", "text": "*Exchange:*\nbinance" },
        { "type": "mrkdwn", "text": "*Severity:*\nalert" },
        { "type": "mrkdwn", "text": "*Type:*\nwhale_movement" }
      ]
    },
    {
      "type": "section",
      "text": { "type": "mrkdwn", "text": "Whale buy detected on Binance: $2.5M BTC market order absorbed in 3 seconds" }
    },
    {
      "type": "context",
      "elements": [
        { "type": "mrkdwn", "text": "Market.ai | 2024-02-24T12:05:00.000Z" }
      ]
    }
  ]
}

Telegram (Markdown)

The payload sent to the Telegram Bot API includes text and parse_mode fields:

{
  "text": "*WHALE MOVEMENT*\n\n*Symbol:* BTC/USDT\n*Exchange:* binance\n*Severity:* alert\n\nWhale buy detected on Binance: $2.5M BTC market order absorbed in 3 seconds\n\n_2024-02-24T12:05:00.000Z_",
  "parse_mode": "Markdown"
}

Retry Behavior

When a webhook delivery fails (non-2xx HTTP response or network error), Market.ai retries with exponential backoff:

Attempt	Delay	Total Time
1st attempt	Immediate	0s
2nd attempt	1 second	1s
3rd attempt	5 seconds	6s
4th attempt	30 seconds	36s

After 3 retries (4 total attempts), the delivery is marked as failed in the delivery log. The webhook remains active for future signals.

You can monitor delivery failures via the GET/v1/webhooks/:id/deliveries endpoint and check the error field on failed deliveries.

Tier Limits

Tier	Max Webhooks
Free	1
Basic ($4.99/mo)	5
Pro ($9.99/mo)	25
Max ($24.99/mo)	Unlimited

Attempting to create a webhook beyond your tier limit returns a 403 Forbidden response.