BillionVerify Webhooks API

openapi: 3.2.0
info:
  title: BillionVerify Webhooks API
  description: 'BillionVerify provides a powerful email verification API for validating email addresses in real-time.


    ## Authentication


    All API endpoints require authentication using an API key. Include your API key in the request header:


    ```

    BILLIONVERIFY-API-KEY: your_api_key_here

    ```


    The following header names are all accepted, in priority order:

    - `BV-API-KEY` *(recommended)*

    - `BILLIONVERIFY-API-KEY`

    - `Authorization: Bearer {api_key}`


    ## Rate Limits


    | Endpoint | Rate Limit |

    |----------|------------|

    | Single Verification (`/verify/single`) | 6,000 requests/minute |

    | Batch Verification (`/verify/bulk`) | 1,500 requests/minute |

    | File Upload (`/verify/file`) | 300 requests/minute |

    | Other endpoints | 200 requests/minute |


    ## Credits & Billing


    - **Unknown** status: 0 credits (we could not reach a deterministic conclusion, so you are not charged)

    - All other statuses (valid, invalid, risky, disposable, catchall, role): 1 credit each


    `invalid` is a deterministic result — we confirmed the address is not deliverable (SMTP 550, missing MX, mailbox not found, etc.) — and is just as valuable for list cleaning as `valid`, so it is billed the same.


    `risky` is likewise deterministic: we completed the full SMTP check *and* found the recipient domain listed by an external blocklist. See `risk_reasons` on the result object.


    > **Changed 2026-08-04.** `risky` previously meant "we could not finish verifying" (an internal capacity fallback) and was not billed. That case is now returned as `unknown`, unchanged in behaviour and still free. `risky` now exclusively means "deliverable, but the domain has a confirmed abuse history — do not send", is billed 1 credit, and is never retryable. If your integration treats `risky` as "retry later", update it.


    ## Base URL


    Production: `https://api.billionverify.com`'
  version: 1.0.0
  contact:
    name: BillionVerify Support
    email: support@billionverify.com
    url: https://billionverify.com
  license:
    name: Proprietary
    url: https://billionverify.com/terms
servers:
- url: https://api.billionverify.com
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Webhooks
  description: Webhook management endpoints
paths:
  /v1/webhooks:
    post:
      tags:
      - Webhooks
      summary: Create webhook
      description: 'Create a new webhook to receive notifications for file verification events.


        **Available events:**

        - `file.completed` - File verification job completed successfully

        - `file.failed` - File verification job failed


        The webhook `secret` is returned only on creation. Store it securely for signature verification.


        **Security requirements:**

        - Webhook URLs must use HTTPS

        - `X-Webhook-Signature` is `sha256=`

        - Verify the signature over `{X-Webhook-Timestamp}.{raw_body}`

        - Reject old timestamps to reduce replay risk'
      operationId: createWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookCreateRequest'
            example:
              url: https://your-app.com/webhooks/billionverify
              events:
              - file.completed
              - file.failed
      responses:
        '200':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                success: true
                code: '0'
                message: Success
                data:
                  id: 673f3bff-81ea-4730-9cef-af1eb7f134bf
                  url: https://your-app.com/webhooks/billionverify
                  events:
                  - file.completed
                  - file.failed
                  secret: 5c609e6893ab3b65ce8940549a030bc165762fe171e0b38f880bd570099619bf
                  is_active: true
                  created_at: '2026-02-04T10:30:00Z'
                  updated_at: '2026-02-04T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    get:
      tags:
      - Webhooks
      summary: List webhooks
      description: 'List all webhooks for the authenticated account. Note that the `secret` is not returned in list responses.


        Delivery health fields:

        - `last_delivery_status` uses `success` or `failed`

        - `last_delivery_at` stores the final delivery timestamp

        - `last_error` stores the final error string when the last delivery failed'
      operationId: listWebhooks
      responses:
        '200':
          description: Webhooks retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                success: true
                code: '0'
                message: Success
                data:
                  webhooks:
                  - id: 673f3bff-81ea-4730-9cef-af1eb7f134bf
                    url: https://your-app.com/webhooks/billionverify
                    events:
                    - file.completed
                    - file.failed
                    is_active: true
                    last_delivery_status: success
                    last_delivery_at: '2026-04-01T12:00:00Z'
                    last_error: null
                    created_at: '2026-02-04T10:30:00Z'
                    updated_at: '2026-02-04T10:30:00Z'
                  total: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/webhooks/{webhook_id}:
    delete:
      tags:
      - Webhooks
      summary: Delete webhook
      description: Delete a webhook by ID.
      operationId: deleteWebhook
      parameters:
      - name: webhook_id
        in: path
        required: true
        description: The webhook ID
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Webhook deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                success: true
                code: '0'
                message: Success
                data:
                  message: Webhook deleted successfully
                  webhook_id: 673f3bff-81ea-4730-9cef-af1eb7f134bf
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            code: '4040'
            message: Not found
            error:
              code: JOB_NOT_FOUND
              message: The specified job was not found
    BadRequest:
      description: Bad request - invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            code: '4000'
            message: Invalid request
            error:
              code: INVALID_REQUEST
              message: Invalid email format
    Unauthorized:
      description: Unauthorized - invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            code: '4010'
            message: Unauthorized
            error:
              code: INVALID_API_KEY
              message: API key is invalid or missing
  schemas:
    WebhookCreateRequest:
      type: object
      required:
      - url
      - events
      properties:
        url:
          type: string
          format: uri
          description: HTTPS URL to receive webhook notifications
          pattern: ^https://
          example: https://your-app.com/webhooks/billionverify
        events:
          type: array
          items:
            type: string
            enum:
            - file.completed
            - file.failed
          description: Events to subscribe to
          example:
          - file.completed
          - file.failed
    ErrorInfo:
      type: object
      properties:
        code:
          type: string
          description: Detailed error code
        message:
          type: string
          description: Detailed error message
        description:
          type:
          - string
          - 'null'
          description: Additional human-readable context (omitempty in Go)
        details:
          description: Additional structured context (any type; usually map or string; omitempty in Go).
    ErrorResponse:
      type: object
      description: 'Standard error response shape. Mirrors Go `response.StandardResponse`

        with Error populated. F23 (2026-05-09) replaced inline error object

        with `$ref ErrorInfo` so all typed wrappers + ErrorResponse share one

        canonical schema.

        '
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Top-level error code (mirrors Go StandardResponse.Code)
        message:
          type: string
          description: Top-level error message
        error:
          $ref: '#/components/schemas/ErrorInfo'
    ApiResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
        code:
          type: string
          description: Response code ("0" for success)
        message:
          type: string
          description: Human-readable message
        data:
          type: object
          description: Response data (varies by endpoint)
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: BV-API-KEY
      description: 'API key for authentication. The following header names are accepted, in priority order:

        - `BV-API-KEY` (recommended)

        - `BILLIONVERIFY-API-KEY`

        - `Authorization: Bearer {api_key}`

        '