Kaminari Ad Webhooks API

openapi: 3.2.0
info:
  title: Kaminari Ad Webhooks API
  description: 'REST API for Kaminari Ad, the ad quality and ad security platform for publishers, ad networks, SSPs and DSPs. Submit ad creatives, ad tags and landing pages for scanning, read verdicts with evidence, manage policies, alerts and webhooks.


    Authenticate with an API key as a Bearer token: https://kaminari.ad/docs/developers/authentication'
  contact:
    name: Kaminari Ad Support
    url: https://kaminari.ad/contact
    email: support@kaminari.ad
  version: 0.1.0
servers:
- url: https://app.kaminari.ad
tags:
- name: Webhooks
paths:
  /api/v1/webhooks:
    get:
      tags:
      - Webhooks
      summary: List Webhooks
      operationId: list_webhooks_api_v1_webhooks_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/WebhookResponse'
                type: array
                title: Response List Webhooks Api V1 Webhooks Get
      security:
      - HTTPBearer: []
    post:
      tags:
      - Webhooks
      summary: Create Webhook
      operationId: create_webhook_api_v1_webhooks_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/v1/webhooks/event-types:
    get:
      tags:
      - Webhooks
      summary: List Event Catalog
      operationId: list_event_catalog_api_v1_webhooks_event_types_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventCatalogResponse'
      security:
      - HTTPBearer: []
  /api/v1/webhooks/{endpoint_id}:
    get:
      tags:
      - Webhooks
      summary: Get Webhook
      operationId: get_webhook_api_v1_webhooks__endpoint_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Webhooks
      summary: Update Webhook
      operationId: update_webhook_api_v1_webhooks__endpoint_id__patch
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Webhooks
      summary: Delete Webhook
      operationId: delete_webhook_api_v1_webhooks__endpoint_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/webhooks/{endpoint_id}/test:
    post:
      tags:
      - Webhooks
      summary: Test Webhook
      operationId: test_webhook_api_v1_webhooks__endpoint_id__test_post
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TestWebhookRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestWebhookResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/webhooks/{endpoint_id}/rotate-secret:
    post:
      tags:
      - Webhooks
      summary: Rotate Webhook Secret
      operationId: rotate_webhook_secret_api_v1_webhooks__endpoint_id__rotate_secret_post
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookCreatedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/webhooks/{endpoint_id}/deliveries:
    get:
      tags:
      - Webhooks
      summary: List Delivery Attempts
      operationId: list_delivery_attempts_api_v1_webhooks__endpoint_id__deliveries_get
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      - name: success
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Success
      - name: from_ts
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: From Ts
      - name: to_ts
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: To Ts
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
          title: Page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_DeliveryAttemptResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/webhooks/deliveries/{attempt_id}/replay:
    post:
      tags:
      - Webhooks
      summary: Replay Delivery
      operationId: replay_delivery_api_v1_webhooks_deliveries__attempt_id__replay_post
      security:
      - HTTPBearer: []
      parameters:
      - name: attempt_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Attempt Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/webhooks/{endpoint_id}/replay:
    post:
      tags:
      - Webhooks
      summary: Bulk Replay
      operationId: bulk_replay_api_v1_webhooks__endpoint_id__replay_post
      security:
      - HTTPBearer: []
      parameters:
      - name: endpoint_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Endpoint Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkReplayRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkReplayResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EndpointHealthResponse:
      properties:
        consecutive_failures:
          type: integer
          title: Consecutive Failures
        last_delivery_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Last Delivery At
        last_delivery_status:
          anyOf:
          - type: integer
          - type: 'null'
          title: Last Delivery Status
        success_rate_7d:
          type: number
          title: Success Rate 7D
        failing_since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Failing Since
        paused_until:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paused Until
      type: object
      required:
      - consecutive_failures
      - last_delivery_at
      - last_delivery_status
      - success_rate_7d
      - failing_since
      - paused_until
      title: EndpointHealthResponse
      description: 'Wire representation of :class:`EndpointHealth`.


        ``failing_since`` is what the UI should render — it says how long the

        partner has actually been down. ``consecutive_failures`` counts

        concurrent attempts and is kept for diagnostics only.'
    BulkReplayRequest:
      properties:
        from_ts:
          type: string
          format: date-time
          title: From Ts
        to_ts:
          type: string
          format: date-time
          title: To Ts
      type: object
      required:
      - from_ts
      - to_ts
      title: BulkReplayRequest
      description: Range filter for bulk-replaying failed deliveries.
    EventCatalogEntryResponse:
      properties:
        event_type:
          type: string
          title: Event Type
        description:
          type: string
          title: Description
        sample_payload:
          additionalProperties: true
          type: object
          title: Sample Payload
      type: object
      required:
      - event_type
      - description
      - sample_payload
      title: EventCatalogEntryResponse
      description: Wire shape of a single catalog entry.
    WebhookCreatedResponse:
      properties:
        webhook:
          $ref: '#/components/schemas/WebhookResponse'
        secret:
          type: string
          title: Secret
      type: object
      required:
      - webhook
      - secret
      title: WebhookCreatedResponse
      description: 'Create / rotate response carrying the cleartext signing secret.


        The caller MUST persist ``secret`` on their side — we never return

        it again. Subsequent ``GET`` requests return only :class:`WebhookResponse`.'
    BulkReplayResponse:
      properties:
        replayed:
          type: integer
          title: Replayed
        skipped:
          type: integer
          title: Skipped
      type: object
      required:
      - replayed
      - skipped
      title: BulkReplayResponse
      description: How many rows were re-armed and how many were skipped.
    EventCatalogResponse:
      properties:
        entries:
          items:
            $ref: '#/components/schemas/EventCatalogEntryResponse'
          type: array
          title: Entries
      type: object
      required:
      - entries
      title: EventCatalogResponse
      description: Entire static catalog; drives the UI event-type checkboxes.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UpdateWebhookRequest:
      properties:
        url:
          anyOf:
          - type: string
            maxLength: 2048
            minLength: 1
          - type: 'null'
          title: Url
        description:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Description
        event_types:
          anyOf:
          - items:
              type: string
            type: array
            uniqueItems: true
          - type: 'null'
          title: Event Types
        campaign_ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
            uniqueItems: true
          - type: 'null'
          title: Campaign Ids
        clear_campaign_ids:
          type: boolean
          title: Clear Campaign Ids
          default: false
        is_active:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Active
      type: object
      title: UpdateWebhookRequest
      description: 'Partial update for a webhook endpoint.


        Fields set to ``None`` are left untouched; explicit ``False`` on

        ``is_active`` pauses the endpoint without deletion.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    CreateWebhookRequest:
      properties:
        url:
          type: string
          maxLength: 2048
          minLength: 1
          title: Url
        description:
          type: string
          maxLength: 256
          title: Description
          default: ''
        event_types:
          items:
            type: string
          type: array
          uniqueItems: true
          title: Event Types
        campaign_ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
            uniqueItems: true
          - type: 'null'
          title: Campaign Ids
      type: object
      required:
      - url
      title: CreateWebhookRequest
      description: Create-webhook request body.
    WebhookResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        url:
          type: string
          title: Url
        description:
          type: string
          title: Description
        event_types:
          items:
            type: string
          type: array
          title: Event Types
        campaign_ids:
          anyOf:
          - items:
              type: string
              format: uuid
            type: array
          - type: 'null'
          title: Campaign Ids
        is_active:
          type: boolean
          title: Is Active
        disabled_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Disabled Reason
        disabled_reason_detail:
          anyOf:
          - type: string
          - type: 'null'
          title: Disabled Reason Detail
        disabled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Disabled At
        health:
          $ref: '#/components/schemas/EndpointHealthResponse'
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
      - id
      - url
      - description
      - event_types
      - campaign_ids
      - is_active
      - disabled_reason
      - disabled_reason_detail
      - disabled_at
      - health
      - created_at
      - updated_at
      title: WebhookResponse
      description: 'Wire shape of a :class:`WebhookEndpoint`.


        Secret material is NEVER included — cleartext is only visible in

        :class:`WebhookCreatedResponse` immediately after creation or

        rotation.'
    TestWebhookRequest:
      properties:
        event_type:
          type: string
          title: Event Type
      type: object
      required:
      - event_type
      title: TestWebhookRequest
      description: Which event type's sample payload to send.
    DeliveryAttemptResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        event_id:
          type: string
          format: uuid
          title: Event Id
        event_type:
          type: string
          title: Event Type
        response_status:
          anyOf:
          - type: integer
          - type: 'null'
          title: Response Status
        response_body:
          anyOf:
          - type: string
          - type: 'null'
          title: Response Body
        success:
          type: boolean
          title: Success
        attempt_number:
          type: integer
          title: Attempt Number
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        elapsed_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Elapsed Ms
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
      - id
      - event_id
      - event_type
      - response_status
      - response_body
      - success
      - attempt_number
      - error_code
      - elapsed_ms
      - created_at
      title: DeliveryAttemptResponse
      description: One row of the partner-facing delivery log.
    TestWebhookResponse:
      properties:
        success:
          type: boolean
          title: Success
        response_status:
          anyOf:
          - type: integer
          - type: 'null'
          title: Response Status
        elapsed_ms:
          type: integer
          title: Elapsed Ms
        error_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Error Code
        response_body:
          type: string
          title: Response Body
      type: object
      required:
      - success
      - response_status
      - elapsed_ms
      - error_code
      - response_body
      title: TestWebhookResponse
      description: Synthetic delivery result for the partner's UI.
    PaginatedResponse_DeliveryAttemptResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/DeliveryAttemptResponse'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
        pages:
          type: integer
          title: Pages
      type: object
      required:
      - items
      - total
      - page
      - limit
      - pages
      title: PaginatedResponse[DeliveryAttemptResponse]
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer