---
title: "Register a webhook"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Register a webhook

`POST /webhooks`

## Request

- Base URL: `https://frontrun.vc/v1`
- URL: `https://frontrun.vc/v1/webhooks`
- Auth: API key in header `X-API-Key`

Register a webhook URL to receive push-delivered signal events instead of polling /feed. Subscribe to event types (new_follow, convergence) with optional filters (e.g. sector); provide `secret` to get signed deliveries. Up to 10 active webhooks per API key (400 when the limit is reached). Costs 40 credits to register, then 8 credits per delivered event. Failed deliveries are retried up to 5 times with increasing backoff.

## Request body

- object
  - `url` string, uri, required: HTTPS endpoint to receive event POSTs.
  - `events` string[], required: Event types to subscribe to (e.g. "new_follow", "convergence").
  - `filters` object: Optional event filters (e.g. sector).
  - `secret` string: Optional signing secret for verifying deliveries.

## Response `201`

Webhook registered.

- object
  - `id` string
  - `url` string
  - `events` string[]
  - `filters` object
  - `status` string
  - `created_at` string, date-time
  - `cost_credits` integer: Credits charged for this call.
  - `balance_credits` integer: Remaining credit balance after this call.

## Other responses

- `400`: Invalid webhook configuration or webhook limit reached.
- `401`: Missing, invalid, inactive, or expired API key.
- `402`: Insufficient credits for this operation. Top up from the developer page or enable auto-refill.
- `429`: Rate limit or daily credit cap reached. Retry after the indicated reset time.

---

[API](https://skmtc.dev/frontrun/apis/frontrun-api.md) · [All operations](https://skmtc.dev/frontrun/apis/frontrun-api/llms.txt) · [OpenAPI document](https://skmtc.dev/frontrun/apis/frontrun-api/revisions/6880b29e94c9?raw)