Webhooks
Push-based delivery of signals. Register a URL and Frontrun POSTs events to it as they happen — no polling. Up to 10 active webhooks per API key.
Cost: 40 credits to register a webhook, then 8 credits per delivered event. Listing, deleting, and viewing delivery history are free.
Register a Webhook
POST /v1/webhooks — 40 credits
curl -X POST https://frontrun.vc/v1/webhooks \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/hooks/frontrun",
"events": ["new_follows", "convergence"],
"filters": {
"sectors": ["AI/ML"],
"is_company_only": true
},
"secret": "whsec_your_signing_secret"
}'Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
url | string (body) | -- | HTTPS endpoint to receive events. Required. Private/loopback addresses are rejected. |
events | string[] (body) | -- | Event types to subscribe to. Required. Values: "new_follows", "convergence" |
filters | object (body) | {} | Only deliver events matching these filters. See below. |
secret | string (body) | -- | Optional signing secret. When set, deliveries include an HMAC-SHA256 signature. |
Filters
| Field | Type | Applies to | Description |
|---|---|---|---|
tracked_accounts | string[] | new_follows | Only fire for follows from these tracked accounts |
sectors | string[] | both | Only entities whose sector matches (case-insensitive partial match) |
entity_types | string[] | new_follows | Only entities whose type matches (e.g. "startup") |
is_company_only | boolean | both | Only fire for entities classified as companies |
min_convergence | integer | convergence | Minimum tracked accounts converging (default 2) |
Response
{
"id": "wh_9f3a2b1c",
"url": "https://example.com/hooks/frontrun",
"events": ["new_follows", "convergence"],
"filters": {
"sectors": ["AI/ML"],
"is_company_only": true
},
"status": "active",
"created_at": "2026-07-08T14:00:00.000Z",
"cost_credits": 40,
"balance_credits": 9960
}A 400 is returned for an invalid URL or event type, or when you already have 10 active webhooks.
Event deliveries
Each delivered event costs 8 credits. Deliveries are POST requests with these headers:
| Header | Description |
|---|---|
X-Frontrun-Event | Event type (new_follows or convergence) |
X-Frontrun-Delivery-Id | Unique delivery ID |
X-Frontrun-Signature | sha256=<hex> — HMAC-SHA256 of the raw body using your secret. Only present if a secret was set. |
new_follows payload
{
"event": "new_follows",
"timestamp": "2026-07-08T14:05:00.000Z",
"data": {
"tracked_account": "pmarca",
"new_follows_count": 1,
"new_follows": [
{
"twitter_user_id": "1234567890",
"username": "stealth_ai_co",
"name": "StealthAI",
"description": "Automating enterprise workflows with LLMs",
"classification": {
"is_company": true,
"sector": "AI/ML",
"entity_type": "startup",
"confidence": "high"
}
}
]
}
}convergence payload
{
"event": "convergence",
"timestamp": "2026-07-08T14:05:00.000Z",
"data": {
"username": "stealth_ai_co",
"name": "StealthAI",
"description": "Automating enterprise workflows with LLMs",
"followed_by": ["pmarca", "naval", "garrytan"],
"convergence_score": 3,
"classification": {
"is_company": true,
"sector": "AI/ML",
"entity_type": "startup"
}
}
}Respond with a 2xx status within 10 seconds. Failed deliveries are retried with backoff; repeated consecutive failures pause the webhook.
List Webhooks
GET /v1/webhooks — Free
curl https://frontrun.vc/v1/webhooks \
-H "X-API-Key: your_api_key"{
"count": 1,
"webhooks": [
{
"id": "wh_9f3a2b1c",
"url": "https://example.com/hooks/frontrun",
"events": ["new_follows", "convergence"],
"filters": { "sectors": ["AI/ML"], "is_company_only": true },
"status": "active",
"consecutive_failures": 0,
"last_delivery_at": "2026-07-08T14:05:00.000Z",
"created_at": "2026-07-08T14:00:00.000Z"
}
]
}Delete a Webhook
DELETE /v1/webhooks/:id — Free
curl -X DELETE https://frontrun.vc/v1/webhooks/wh_9f3a2b1c \
-H "X-API-Key: your_api_key"{
"deleted": true,
"id": "wh_9f3a2b1c"
}Delivery History
GET /v1/webhooks/:id/deliveries — Free
curl "https://frontrun.vc/v1/webhooks/wh_9f3a2b1c/deliveries?limit=50" \
-H "X-API-Key: your_api_key"Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
id | string (path) | -- | Webhook ID. Required. |
limit | integer (query) | 50 | Maximum deliveries returned (max 200). |
Response
{
"webhook_id": "wh_9f3a2b1c",
"count": 2,
"deliveries": [
{
"id": "del_7c1e4d9a",
"event_type": "new_follows",
"status_code": 200,
"response_ms": 142,
"attempt": 1,
"delivered_at": "2026-07-08T14:05:00.000Z"
},
{
"id": "del_5b0d3c8f",
"event_type": "convergence",
"status_code": 500,
"response_ms": 310,
"attempt": 2,
"delivered_at": "2026-07-08T13:40:00.000Z"
}
]
}