openapi: 3.0.3
info:
  title: SimilarWeb Batch Account Webhooks API
  description: The SimilarWeb Batch API is optimized for large-scale bulk data extraction, supporting asynchronous jobs of up to one million domains per request. It delivers data to cloud storage destinations including Amazon S3, Google Cloud Storage, and Snowflake. The API covers website traffic, keywords, referrals, geography, segments, apps, companies, e-commerce, and technographics datasets.
  version: 4.0.0
  termsOfService: https://www.similarweb.com/corp/legal/terms-of-use/
  contact:
    name: SimilarWeb Support
    url: https://support.similarweb.com/hc/en-us/articles/22089555897373-REST-API
  license:
    name: Proprietary
    url: https://www.similarweb.com/corp/legal/terms-of-use/
servers:
- url: https://api.similarweb.com
  description: SimilarWeb API server
tags:
- name: Webhooks
  description: Webhook subscription management for data-ready notifications
paths:
  /batch/v4/webhooks/subscribe:
    post:
      operationId: subscribeWebhook
      summary: Subscribe to Webhook Events
      description: Subscribe to event notifications to stay updated on data releases and report completions.
      tags:
      - Webhooks
      security:
      - apiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscribeRequest'
      responses:
        '200':
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
  /batch/v4/webhooks/list:
    get:
      operationId: listWebhookSubscriptions
      summary: List Webhook Subscriptions
      description: Retrieve all active webhook subscriptions for the account.
      tags:
      - Webhooks
      security:
      - apiKeyHeader: []
      responses:
        '200':
          description: List of webhook subscriptions
          content:
            application/json:
              schema:
                type: object
                properties:
                  subscriptions:
                    type: array
                    items:
                      $ref: '#/components/schemas/WebhookSubscription'
        '400':
          $ref: '#/components/responses/BadRequest'
  /batch/v4/webhooks/unsubscribe:
    delete:
      operationId: unsubscribeWebhook
      summary: Unsubscribe from Webhook Events
      description: Remove a webhook subscription.
      tags:
      - Webhooks
      security:
      - apiKeyHeader: []
      parameters:
      - name: webhook_id
        in: query
        required: true
        schema:
          type: string
        description: Webhook subscription ID to remove
      responses:
        '200':
          description: Subscription removed
        '400':
          $ref: '#/components/responses/BadRequest'
  /batch/v4/webhooks/test:
    post:
      operationId: testWebhook
      summary: Test Your Webhooks
      description: Send a test notification to a webhook URL to verify configuration.
      tags:
      - Webhooks
      security:
      - apiKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - webhook_url
              properties:
                webhook_url:
                  type: string
                  format: uri
                  description: The webhook URL to test
      responses:
        '200':
          description: Test notification sent
        '400':
          $ref: '#/components/responses/BadRequest'
components:
  responses:
    BadRequest:
      description: Bad request - invalid parameters or missing required fields
      content:
        application/json:
          schema:
            type: object
  schemas:
    WebhookSubscription:
      type: object
      properties:
        webhook_id:
          type: string
          description: Unique identifier for the subscription
        webhook_url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
          - active
          - inactive
    WebhookSubscribeRequest:
      type: object
      required:
      - webhook_url
      - events
      properties:
        webhook_url:
          type: string
          format: uri
          description: URL to receive event notifications
        events:
          type: array
          items:
            type: string
          description: Event types to subscribe to (e.g., data_release, report_complete)
        secret:
          type: string
          description: Optional secret for webhook signature verification
  securitySchemes:
    apiKeyHeader:
      type: apiKey
      in: header
      name: api-key
      description: SimilarWeb API key passed as a request header
externalDocs:
  description: SimilarWeb Batch API Documentation
  url: https://developers.similarweb.com/docs/intro-to-the-batch-api-datasets.md