Hubble Network Packet Webhooks API

openapi: 3.2.0
info:
  title: Hubble Platform Packet Webhooks API
  description: The Hubble platform is built API-first.
  version: 1.0.0
servers:
- url: https://api.hubble.com
  description: Production
security:
- BearerAuth: []
tags:
- name: Packet Webhooks
paths:
  /v1/org/{org_id}/webhooks:
    post:
      tags:
      - Packet Webhooks
      operationId: create-webhook-endpoint
      x-criticality: high
      summary: Create a Webhook Endpoint
      description: 'Register an endpoint that can receive webhook events for packet data.


        **Required Scope:** `write-webhooks`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  $ref: '#/components/schemas/webhookURL'
                max_batch_size:
                  $ref: '#/components/schemas/webhookMaxBatchSize'
                name:
                  $ref: '#/components/schemas/webhookName'
      responses:
        '200':
          description: A registered webhook endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhookWithSecret'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
    get:
      tags:
      - Packet Webhooks
      operationId: list-registered-webhooks
      x-criticality: high
      summary: List Registered Webhooks
      description: 'Retrieve a list of registered webhooks.


        **Required Scope:** `read-webhooks`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      responses:
        '200':
          description: A list of registered webhook endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/basicWebhook'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/webhooks/{webhook_id}:
    patch:
      tags:
      - Packet Webhooks
      operationId: update-webhook-endpoint
      x-criticality: high
      summary: Update a Webhook Endpoint
      description: 'Update certain fields of a webhook endpoint.


        **Required Scope:** `write-webhooks`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - $ref: '#/components/parameters/webhookIdPathParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                set_name:
                  $ref: '#/components/schemas/webhookName'
                set_max_batch_size:
                  $ref: '#/components/schemas/webhookMaxBatchSize'
                set_url:
                  $ref: '#/components/schemas/webhookURL'
      responses:
        '200':
          description: The updated webhook endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basicWebhook'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
    delete:
      tags:
      - Packet Webhooks
      operationId: delete-webhook-endpoint
      x-criticality: high
      summary: Delete a Webhook Endpoint
      description: 'Delete a webhook endpoint.


        **Required Scope:** `write-webhooks`

        Delete a webhook endpoint so that it will stop receiving traffic.'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - $ref: '#/components/parameters/webhookIdPathParam'
      responses:
        '200':
          description: The webhook has been deleted
          content:
            application/json:
              schema:
                type: object
                description: an empty object for now
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
  /v1/org/{org_id}/webhooks/{webhook_id}/test:
    post:
      tags:
      - Packet Webhooks
      operationId: test-webhook-endpoint
      x-criticality: high
      summary: Send a Test Webhook
      description: 'Send an example packet batch to the configured webhook URL to test webhook delivery

        (connectivity, authentication, and response handling). Uses the same request shape as

        live delivery (JSON packet batch plus `HTTP-X-HUBBLE-TOKEN` when a secret is configured).

        The example packet is ephemeral and is not persisted after one attempt.


        **Required Scope:** `write-webhooks`'
      parameters:
      - $ref: '#/components/parameters/orgIdPathParam'
      - $ref: '#/components/parameters/webhookIdPathParam'
      responses:
        '200':
          description: Result of the test webhook delivery attempt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/testWebhookResponse'
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
components:
  schemas:
    webhookId:
      type: string
      description: An identifier for a webhook
    legacyWebhook:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/webhookURL'
        max_batch_size:
          $ref: '#/components/schemas/webhookMaxBatchSize'
    testWebhookResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the webhook endpoint returned a successful HTTP status code
        status_code:
          type: integer
          description: HTTP status code returned by the webhook endpoint, if a response was received
        error:
          type: string
          description: Error details when the test delivery failed
    webhookWithSecret:
      type: object
      allOf:
      - $ref: '#/components/schemas/basicWebhook'
      - type: object
        properties:
          secret:
            $ref: '#/components/schemas/webhookSecret'
    errorResponse:
      type: object
      properties:
        code:
          type: integer
          description: The HTTP status code
        description:
          type: string
          description: 'A description for the error.

            For user errors, we attempt to be as descriptive as possible to help with diagnosing the issue.

            For internal errors, the error description is only indicates that a retry should occur but we log the full error so that we can diagnose it.

            Error descriptions can change over time and should not be programmed against.

            '
        name:
          type: string
          enum:
          - Bad Request
          - Unauthorized
          - Not Found
          - Too Many Requests
          - Internal Server Error
          description: '`name` is a short name for the error.

            '
    basicWebhook:
      type: object
      allOf:
      - $ref: '#/components/schemas/legacyWebhook'
      - type: object
        properties:
          webhook_id:
            $ref: '#/components/schemas/webhookId'
          org_id:
            $ref: '#/components/schemas/orgId'
          name:
            $ref: '#/components/schemas/webhookName'
    orgId:
      type: string
      format: uuid
      description: The ID for an organization
    webhookSecret:
      type: string
      description: 'A confidential, unique string generated for your webhook endpoint to validate that the request came from Hubble.

        Hubble will send this token in the HTTP header `HTTP-X-HUBBLE-TOKEN` when making HTTPS requests to your endpoint.

        '
    webhookURL:
      type: string
      description: A webhook url
      maxLength: 2000
    webhookName:
      type: string
      description: A name/description for a webhook
      maxLength: 250
    webhookMaxBatchSize:
      type: integer
      description: The maximum number of packets that Hubble will batch into one webhook request
      default: 100
      minimum: 10
      maximum: 1000
  responses:
    ErrorInternalServer:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 500
            description: An unknown error has occurred.
            name: Unknown
    ErrorBadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 400
            description: The request could not be understood by the server due to malformed syntax.
            name: Bad Request
    ErrorNotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 404
            description: The requested resource was not found.
            name: Not Found
  parameters:
    orgIdPathParam:
      name: org_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/orgId'
      description: Your organization ID
    webhookIdPathParam:
      name: webhook_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/webhookId'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT