---
title: "Register a webhook for new matching lots (Pro+, max 3 per account)"
method: POST
path: "/api/v1/webhooks"
---

# Register a webhook for new matching lots (Pro+, max 3 per account)

`POST /api/v1/webhooks`

## Request

- Base URL: `https://bidprowl.com`
- URL: `https://bidprowl.com/api/v1/webhooks`
- Auth: HTTP bearer

New lots matching the filters are POSTed to `url` as the `newLots` webhook below, checked every 10 minutes. The response carries the signing `secret` ONCE. Delivery is at least once: dedupe on lot id. 20 consecutive failed deliveries disable the webhook; last_error says why.

## Request body

- object
  - `url` string, uri, required: https, public host
  - `description` string
  - `filters` WebhookFilters, required: Same vocabulary as GET /api/v1/listings. At least one of q, category, state, source or zip is required.
    - `q` string
    - `category` string
    - `state` string: 2-letter code
    - `source` string
    - `zip` string
    - `radius_miles` integer
    - `price_min` number: USD (input only; stored as price_min_cents)
    - `price_max` number: USD (input only; stored as price_max_cents)

## Response `201`

Created. `secret` is never shown again.

- object
  - `data` object
    - `id` string, uuid
    - `url` string, uri
    - `description` string, nullable
    - `filters` object: Stored filters; prices in cents (price_min_cents, price_max_cents).
    - `secret_prefix` string
    - `enabled` boolean: false once 20 consecutive deliveries failed
    - `consecutive_failures` integer
    - `last_error` string, nullable
    - `last_attempt_at` string, date-time, nullable
    - `last_success_at` string, date-time, nullable
    - `disabled_at` string, date-time, nullable
    - `delivered_count` integer
    - `created_at` string, date-time
    - `secret` string

## Other responses

- `400`: Invalid url or filters.
- `401`: Missing, invalid or revoked API key.
- `403`: The key is valid but the plan does not include this data.
- `409`: The account already has 3 webhooks.
- `429`: Per-minute burst limit or monthly quota exhausted. Read Retry-After, and RateLimit-* to self-throttle before you get here.

---

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