openapi: 3.2.0
info:
  title: Scope3 Buyer Webhook Subscriptions API
  version: 2.0.0
  description: 'REST API for advertisers to manage advertisers, campaigns, and reporting.


    ## Authentication


    All endpoints require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer your-api-key

    ```


    ## Base URL


    `https://api.interchange.io/api/v2/buyer`


    ## For AI Agents


    AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools:

    - `initialize`: Start an MCP session

    - `api_call`: Make REST API calls

    - `ask_about_capability`: Learn about API features'
servers:
- url: https://api.interchange.io/api/v2/buyer
  description: Production server
tags:
- name: Webhook Subscriptions
paths:
  /webhook-subscriptions:
    post:
      operationId: createWebhookSubscription
      summary: Register a webhook subscription
      description: Register a webhook endpoint to receive push events for subscribed event types, starting with `discovery.revision` (progressive discovery updates — see the SSE-equivalent `GET /discovery/{discoveryId}/events`). Deliveries are HMAC-SHA256 signed with the provided secret in the `X-Webhook-Signature` header.
      tags:
      - Webhook Subscriptions
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  maxLength: 2048
                  format: uri
                secret:
                  type: string
                  minLength: 16
                  maxLength: 256
                eventTypes:
                  minItems: 1
                  type: array
                  items:
                    type: string
                    enum:
                    - discovery.revision
              required:
              - url
              - secret
              - eventTypes
      responses:
        '201':
          description: Register a webhook subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuyerWebhookSubscriptionResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: listWebhookSubscriptions
      summary: List webhook subscriptions
      description: List the authenticated customer's webhook subscriptions.
      tags:
      - Webhook Subscriptions
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List webhook subscriptions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListBuyerWebhookSubscriptionsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /webhook-subscriptions/{id}:
    delete:
      operationId: deleteWebhookSubscription
      summary: Delete a webhook subscription
      description: Remove a webhook subscription. Deliveries stop immediately.
      tags:
      - Webhook Subscriptions
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: id
        schema:
          type: string
          minLength: 1
        required: true
      responses:
        '200':
          description: Delete a webhook subscription
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteBuyerWebhookSubscriptionResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No webhook subscription with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    BuyerWebhookSubscription:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
        eventTypes:
          type: array
          items:
            type: string
            enum:
            - discovery.revision
        status:
          type: string
          enum:
          - active
          - inactive
          - failed
        failureCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        lastSuccess:
          type:
          - string
          - 'null'
        lastFailure:
          type:
          - string
          - 'null'
        createdAt:
          type: string
        updatedAt:
          type: string
      required:
      - id
      - url
      - eventTypes
      - status
      - failureCount
      - lastSuccess
      - lastFailure
      - createdAt
      - updatedAt
      additionalProperties: false
    ErrorResponse:
      description: Standard error response
      type: object
      properties:
        data:
          type:
          - string
          - 'null'
          enum:
          - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
      - data
      - error
      additionalProperties: false
    ListBuyerWebhookSubscriptionsResponse:
      type: object
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/BuyerWebhookSubscription'
      required:
      - subscriptions
      additionalProperties: false
    ApiError:
      description: Structured error object
      type: object
      properties:
        code:
          description: Machine-readable error code
          type: string
        message:
          description: Human-readable error message
          type: string
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
      - code
      - message
      additionalProperties: false
    DeleteBuyerWebhookSubscriptionResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
          - true
        id:
          type: string
      required:
      - success
      - id
      additionalProperties: false
    BuyerWebhookSubscriptionResponse:
      type: object
      properties:
        subscription:
          $ref: '#/components/schemas/BuyerWebhookSubscription'
      required:
      - subscription
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token