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: Registering a webhook and each delivered event draw on your monthly usage. Listing, deleting, and viewing delivery history are free.
Register a Webhook
POST /v1/webhooks - draws on your monthly usage
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", "people", "accelerators". The last two need the lane on your plan (403 lanes_not_enabled otherwise). |
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 |
only | string | new_follows | "companies" (default), "people" or "all". See People and raw follows |
min_convergence | integer | convergence | Minimum tracked accounts converging (default 2) |
lanes | string[] | people | Only these lanes: stealth, follow, convergence |
programs | string[] | accelerators | Only these accelerator keys, e.g. ["yc", "speedrun"] |
stealth_only | boolean | accelerators | Only stealth teams |
tracked_only | boolean | people, accelerators | Only rows one of your tracked accounts follows |
sectors also applies to accelerators (the company's sector).
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",
"usage_pct": 12,
"usage_resets_at": "2026-11-01T00:00:00Z"
}A 400 is returned for an invalid URL or event type, or when you already have 10 active webhooks.
Event deliveries
Each delivered event draws on your monthly usage. Deliveries are POST requests with these headers:
| Header | Description |
|---|---|
X-Frontrun-Event | Event type (new_follows, convergence, people or accelerators) |
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"
}
}
]
}
}People and raw follows
By default new_follows fires for the companies in your report. Set filters.only to "people" to get every individual your tracked accounts followed instead (researchers, operators, founders before the company exists), or "all" for the raw follow diff.
{ "url": "https://example.com/hook", "events": ["new_follows"], "filters": { "only": "people" } }These deliver once a day (about 6 PM ET, after the day's follows are indexed), grouped by tracked account, up to 500 follows per delivery. Each follow is delivered exactly once.
{
"event": "new_follows",
"timestamp": "2026-11-03T23:05:00Z",
"data": {
"filter": "people",
"total_new_follows": 2,
"results": [
{
"tracked_account": "pmarca",
"as_of": "2026-11-03",
"compared_against": "2026-11-02",
"new_follows_count": 2,
"new_follows": [
{ "twitter_user_id": "1234567890", "username": "jane_doe", "name": "Jane Doe", "description": "ex-DeepMind", "classification": { "is_company": false, "entity_type": "person" } }
]
}
]
}
}tracked_accounts narrows these too. The pull equivalent is GET /v1/follows/new?only=people.
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"
}
}
}people payload
The day's new stealth founders, delivered once when the lane publishes (about 6 AM ET). One delivery per day per webhook, carrying every new row that passes your filters; nothing is sent on a day with no new rows. Rows have the same shape as GET /v1/people: card copy and links, with followed_by drawn from your own tracked accounts only.
{
"event": "people",
"timestamp": "2026-10-27T10:05:00.000Z",
"data": {
"report_date": "2026-10-27",
"count": 2,
"people": [
{
"entity_id": "b917b9ed-e228-491f-adc9-3980fde6d151",
"name": "Jane Park",
"username": "janepark",
"x_username": "janepark",
"lane": "stealth",
"signal_type": "departed_role",
"linkedin_url": "https://www.linkedin.com/in/janepark",
"judge": { "card": { "who": "Ex-Stripe infra engineer", "building": "Stealth: developer infrastructure", "credentials": ["Stripe (2020-2026)"] } },
"followed_by": ["garrytan"],
"tracked_by": [],
"followed_by_count": 1
}
]
}
}accelerators payload
The day's new accelerator cohort companies, same cadence. Rows have the same shape as GET /v1/accelerators.
{
"event": "accelerators",
"timestamp": "2026-10-27T10:05:00.000Z",
"data": {
"report_date": "2026-10-27",
"count": 1,
"companies": [
{
"entity_id": "13abbc29-f7bf-4ac8-8b04-3612647ef5cc",
"name": "Evident Machines",
"handle": "evidentmachines",
"accelerator": "yc",
"batch": "Fall 2026",
"sector": "AI",
"stealth": false,
"one_liner": "Real-world benchmarks for electrical engineering",
"website": "https://evidentmachines.com/",
"founders": [{ "name": "Trishala Jain", "x_handle": "hitrishala", "linkedin_url": "https://www.linkedin.com/in/trishalajain7" }],
"followed_by": []
}
]
}
}A lane event is only ever delivered to an account whose plan includes that lane, checked at delivery time. If the lane leaves your plan, deliveries stop the same day.
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"
}
]
}