Docs
API Reference
Webhooks

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

ParameterTypeDefaultDescription
urlstring (body)--HTTPS endpoint to receive events. Required. Private/loopback addresses are rejected.
eventsstring[] (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).
filtersobject (body){}Only deliver events matching these filters. See below.
secretstring (body)--Optional signing secret. When set, deliveries include an HMAC-SHA256 signature.

Filters

FieldTypeApplies toDescription
tracked_accountsstring[]new_followsOnly fire for follows from these tracked accounts
sectorsstring[]bothOnly entities whose sector matches (case-insensitive partial match)
entity_typesstring[]new_followsOnly entities whose type matches (e.g. "startup")
is_company_onlybooleanbothOnly fire for entities classified as companies
onlystringnew_follows"companies" (default), "people" or "all". See People and raw follows
min_convergenceintegerconvergenceMinimum tracked accounts converging (default 2)
lanesstring[]peopleOnly these lanes: stealth, follow, convergence
programsstring[]acceleratorsOnly these accelerator keys, e.g. ["yc", "speedrun"]
stealth_onlybooleanacceleratorsOnly stealth teams
tracked_onlybooleanpeople, acceleratorsOnly 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:

HeaderDescription
X-Frontrun-EventEvent type (new_follows, convergence, people or accelerators)
X-Frontrun-Delivery-IdUnique delivery ID
X-Frontrun-Signaturesha256=<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

ParameterTypeDefaultDescription
idstring (path)--Webhook ID. Required.
limitinteger (query)50Maximum 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"
    }
  ]
}