BidProwl Webhooks API

openapi: 3.2.0
info:
  title: BidProwl Webhooks API
  version: 1.0.0
  description: 'US government surplus auctions: live listings from 27 official sources with ZIP-radius search, sold-price comparables from 200,000+ closed auctions, nearly all from the last 12 months, and Flip Scores. Free tier: 1,000 calls/month. Get a key at https://bidprowl.com/account/api-keys.'
  contact:
    email: hello@bidprowl.com
    url: https://bidprowl.com/developers
  x-versioning:
    scheme: URL path (/api/v1). A breaking change ships as /api/v2; /api/v1 is never broken in place.
    deprecationPolicy: A deprecated endpoint returns the RFC 8594 `Deprecation` header with the date it was deprecated, and `Sunset` with the date it stops responding. Sunset is never less than 180 days after Deprecation, and both are announced at https://bidprowl.com/developers before they are sent.
    contact: hello@bidprowl.com
servers:
- url: https://bidprowl.com
security:
- bearerAuth: []
tags:
- name: Webhooks
paths:
  /api/v1/webhooks:
    get:
      operationId: listWebhooks
      summary: This account's webhooks with delivery health (no secrets)
      responses:
        '200':
          description: Webhooks
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Webhook'
                  max:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Webhooks
    post:
      operationId: createWebhook
      summary: Register a webhook for new matching lots (Pro+, max 3 per account)
      description: '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.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - url
              - filters
              properties:
                url:
                  type: string
                  format: uri
                  description: https, public host
                description:
                  type: string
                  maxLength: 100
                filters:
                  $ref: '#/components/schemas/WebhookFilters'
            example:
              url: https://example.com/hooks/bidprowl
              filters:
                q: forklift
                state: TX
                price_max: 5000
      responses:
        '201':
          description: Created. `secret` is never shown again.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    allOf:
                    - $ref: '#/components/schemas/Webhook'
                    - type: object
                      properties:
                        secret:
                          type: string
        '400':
          description: Invalid url or filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: The account already has 3 webhooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Webhooks
  /api/v1/webhooks/{id}:
    delete:
      operationId: deleteWebhook
      summary: Delete one of this account's webhooks
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Webhooks
webhooks:
  newLots:
    post:
      summary: New lots matching a registered webhook's filters
      description: Sent to the webhook's url, up to 100 lots per request, oldest first. Verify X-BidProwl-Signature = hex(HMAC-SHA256(secret, raw body)) before trusting it. Answer 2xx within 10 seconds; anything else (including a redirect) counts as a failure and the same lots are re-sent next run. Dedupe on lot id.
      parameters:
      - name: X-BidProwl-Signature
        in: header
        required: true
        schema:
          type: string
      - name: X-BidProwl-Webhook-Id
        in: header
        required: true
        schema:
          type: string
      - name: X-BidProwl-Delivery
        in: header
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook_id:
                  type: string
                  format: uuid
                event:
                  type: string
                  enum:
                  - listings.new
                sent_at:
                  type: string
                  format: date-time
                count:
                  type: integer
                lots:
                  type: array
                  items:
                    $ref: '#/components/schemas/Listing'
      responses:
        '200':
          description: Received
      tags:
      - Webhooks
components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        description:
          type:
          - string
          - 'null'
        filters:
          type: object
          description: Stored filters; prices in cents (price_min_cents, price_max_cents).
        secret_prefix:
          type: string
        enabled:
          type: boolean
          description: false once 20 consecutive deliveries failed
        consecutive_failures:
          type: integer
        last_error:
          type:
          - string
          - 'null'
        last_attempt_at:
          type:
          - string
          - 'null'
          format: date-time
        last_success_at:
          type:
          - string
          - 'null'
          format: date-time
        disabled_at:
          type:
          - string
          - 'null'
          format: date-time
        delivered_count:
          type: integer
        created_at:
          type: string
          format: date-time
    Listing:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        category:
          type: string
          description: 'One of: vehicles, heavy-equipment, electronics, office-furniture (displayed as Furniture), tools-industrial, medical-scientific, military-surplus, real-estate, seized-property, jewelry-coins, apparel, toys-media, appliances, sporting-outdoor, antiques-collectibles, vehicle-parts (parts and accessories; whole vehicles stay in vehicles), other'
        source:
          type: string
          description: Source key, e.g. govdeals
        source_name:
          type: string
        state:
          type:
          - string
          - 'null'
          description: 2-letter US state code
        city:
          type:
          - string
          - 'null'
        zip:
          type:
          - string
          - 'null'
        current_bid_cents:
          type:
          - integer
          - 'null'
        buy_now_cents:
          type:
          - integer
          - 'null'
        starting_bid_cents:
          type:
          - integer
          - 'null'
        num_bids:
          type: integer
        flip_score:
          type:
          - integer
          - 'null'
          description: BidProwl deal score
        condition_grade:
          type:
          - string
          - 'null'
        vin:
          type:
          - string
          - 'null'
          description: '17-character vehicle identification number when the source publishes one (validated: no I, O or Q), else null'
        quantity:
          type:
          - integer
          - 'null'
          description: 'Units in the lot, from the source''s own field or the count its title or description states ("Lot of (5) ..."). Null when not stated, which is most lots: null does not mean 1'
        quantity_approx:
          type:
          - boolean
          - 'null'
          description: True when the stated count is approximate ("approx 50", "40+"); null when quantity is null
        quantity_unit:
          type:
          - string
          - 'null'
          enum:
          - item
          - container
          - null
          description: item, or container when the count is of pallets, boxes or cases; null when quantity is null
        bid_is_per_unit:
          type: boolean
          description: True when the source takes bids per unit (HiBid lots shown as "x 20"). current_bid_cents is then the lot total, unit bid times quantity
        unit_bid_cents:
          type:
          - integer
          - 'null'
          description: current_bid_cents divided by quantity when quantity > 1, the count is exact and there is a bid; the source's per-unit bid when bid_is_per_unit
        image_url:
          type:
          - string
          - 'null'
        start_date:
          type:
          - string
          - 'null'
          format: date-time
        end_date:
          type:
          - string
          - 'null'
          format: date-time
        status:
          type: string
        bidprowl_url:
          type: string
        source_url:
          type: string
          description: Official auction page where bidding happens
    WebhookFilters:
      type: object
      description: Same vocabulary as GET /api/v1/listings. At least one of q, category, state, source or zip is required.
      properties:
        q:
          type: string
        category:
          type: string
        state:
          type: string
          description: 2-letter code
        source:
          type: string
        zip:
          type: string
        radius_miles:
          type: integer
          minimum: 1
          maximum: 300
          default: 50
        price_min:
          type: number
          description: USD (input only; stored as price_min_cents)
        price_max:
          type: number
          description: USD (input only; stored as price_max_cents)
    Error:
      type: object
      required:
      - error
      - code
      - docs
      properties:
        error:
          type: string
          description: Human-readable message.
        code:
          type: string
          description: Machine-readable code. Branch on this, never on `error`.
          enum:
          - missing_api_key
          - invalid_api_key
          - forbidden
          - not_found
          - invalid_request
          - burst_rate_exceeded
          - monthly_quota_exceeded
          - service_busy
          - internal_error
        docs:
          type: string
          format: uri
        upgrade:
          type: string
          format: uri
          description: Present only when upgrading actually resolves the failure.
  responses:
    NotFound:
      description: No such listing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The key is valid but the plan does not include this data.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Per-minute burst limit or monthly quota exhausted. Read Retry-After, and RateLimit-* to self-throttle before you get here.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing, invalid or revoked API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  headers:
    Retry-After:
      description: Seconds to wait before retrying. Sent on every 429.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the monthly window resets (delta-seconds, per the RFC draft).
      schema:
        type: integer
    RateLimit-Remaining:
      description: Calls left in the current monthly window.
      schema:
        type: integer
    RateLimit-Limit:
      description: Calls allowed in the current monthly window.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key (bp_live_...) from bidprowl.com/account/api-keys