Hubble Network Packet Webhooks API

openapi: 3.2.0
info:
  title: Hubble Platform Packet Webhooks API
  description: 'The Hubble platform is built API-first. Use our Cloud API to manage your devices

    and access device data programmatically. We''ve designed our API following RESTful principles. Each endpoint returns standard HTTP status codes and may include JSON payloads. ---


    ## API Access

    Use API Keys to authenticate with the Hubble Cloud API for your organization. ### Generate an API Key

    Log in to your Hubble dashboard. Navigate to **Developer Tools > API Tokens** to create a new API Key. Provide a name for the token, and set an appropriate expiration date for temporary access. ### Organization ID

    You will need `org_id` to make API requests. From your Hubble dashboard, navigate to

    **Developer Tooks > API Tokens**, or **Organization Settings**, to find your Organization ID. ### Authorization Scopes

    API endpoints require specific authorization scopes to perform the intended operation. **Required Scope** is always provided in the API documentation. API Keys can be created with specific authorization scopes that control what operations the key can perform. If no scopes are specified, the key will be created with all available scopes (admin-level access). | **Scope** | **Access** |

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

    | **read-api-keys** | View API keys and their metadata |

    | **write-api-keys** | Create, update, and delete API keys |

    | **read-users** | View user information and roles |

    | **write-users** | Add, update, and remove users from the organization |

    | **read-organization-metadata** | View organization details and settings |

    | **write-organization-metadata** | Update organization information |

    | **read-devices** | View device information and status |

    | **write-devices** | Register and manage devices |

    | **read-invitations** | View pending invitations |

    | **write-invitations** | Create and revoke user invitations |

    | **read-packets** | Access packet data and retrieval endpoints |

    | **read-platform-metrics** | View platform metrics and analytics |

    | **read-billing-usage** | View billing usage information |

    | **read-billing-invoices** | View billing invoices |

    | **read-webhooks** | View webhook configurations |

    | **write-webhooks** | Create and manage webhook endpoints |

    | **read-satellites** | View satellite ephemeris and pass data |


    **Example Scope Combinations**

    - Create a key with read-only access: `["read-api-keys", "read-users", "read-devices"]`

    - Create a key for device management: `["read-devices", "write-devices"]`

    - Create a key for user management: `["read-users", "write-users", "read-invitations", "write-invitations"]`


    **Best Practices for Data Security**

    - Create keys with the minimum required scopes for your use case

    - Regularly review and rotate API keys

    - Use descriptive names for your keys to track their purpose

    - Set appropriate expiration dates for temporary access


    ---


    ## Import API Definition

    You can quickly import the Hubble Cloud API into your preferred developer environment (such as Postman or Insomnia) using our **public OpenAPI definition**. Simply download or import the YAML file directly:


    https://hubble.com/docs/openapi.yaml


    ---


    ## Pagination

    When the number of objects requested exceeds the maximum page size for an endpoint, the API response will be paginated. This means you will receive a subset of the total results, along with a `Continuation-Token` in the Response Header that can be used to fetch subsequent subsets. To retrieve the next set of data, you must use the provided `Continuation-Token` in the Request Header of your next API call to the same endpoint. Continue using the provided token in each successive request until no `Continuation-Token` is returned, which indicates you have retrieved all available data. ---


    ## Rate Limits

    The Hubble Cloud API follows a leaky bucket approach to rate limiting. Endpoints are rate limited to three (3) requests per second. Your organization is limited to a total of 15 requests per second.'
  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'
            example:
              url: https://api.yourdomain.com/webhooks/hubble
              name: Warehouse Packet Delivery
              max_batch_size: 25
      responses:
        '200':
          description: A registered webhook endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhookWithSecret'
              example:
                webhook_id: 6ea53e36-b7fb-429f-8c2e-d536cab71089
                org_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Warehouse Packet Delivery
                url: https://api.yourdomain.com/webhooks/hubble
                max_batch_size: 25
                secret: <shown once, at creation time>
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '413':
          $ref: '#/components/responses/ErrorRequestEntityTooLarge'
        '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'
              example:
                webhooks:
                - webhook_id: 6ea53e36-b7fb-429f-8c2e-d536cab71089
                  org_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                  name: Warehouse Packet Delivery
                  url: https://api.yourdomain.com/webhooks/hubble
                  max_batch_size: 11
        '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'
            example:
              set_name: Warehouse Packet Delivery
              set_max_batch_size: 11
      responses:
        '200':
          description: The updated webhook endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/basicWebhook'
              example:
                webhook_id: 6ea53e36-b7fb-429f-8c2e-d536cab71089
                org_id: 3fa85f64-5717-4562-b3fc-2c963f66afa6
                name: Warehouse Packet Delivery
                url: https://api.yourdomain.com/webhooks/hubble
                max_batch_size: 11
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '413':
          $ref: '#/components/responses/ErrorRequestEntityTooLarge'
        '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'
              example:
                success: true
                status_code: 200
        '400':
          $ref: '#/components/responses/ErrorBadRequest'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
        '500':
          $ref: '#/components/responses/ErrorInternalServer'
components:
  schemas:
    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
    webhookName:
      type: string
      description: A name/description for a webhook
      maxLength: 250
    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
          - Request Entity Too Large
          - Too Many Requests
          - Internal Server Error
          description: '`name` is a short name for the error.

            '
    webhookMaxBatchSize:
      type: integer
      description: The maximum number of packets that Hubble will batch into one webhook request
      default: 100
      minimum: 10
      maximum: 1000
    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
    webhookId:
      type: string
      description: An identifier for a webhook
    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
    legacyWebhook:
      type: object
      properties:
        url:
          $ref: '#/components/schemas/webhookURL'
        max_batch_size:
          $ref: '#/components/schemas/webhookMaxBatchSize'
  parameters:
    webhookIdPathParam:
      name: webhook_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/webhookId'
    orgIdPathParam:
      name: org_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/orgId'
      description: Your organization ID
  responses:
    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
    ErrorInternalServer:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 500
            description: An unknown error has occurred.
            name: Unknown
    ErrorRequestEntityTooLarge:
      description: Request Entity Too Large
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorResponse'
          example:
            code: 413
            description: request body exceeds the maximum allowed size of 1000000 bytes
            name: Request Entity Too Large
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-provenance:
  method: harvested
  publisher: Hubble Network
  source: https://hubble.com/docs/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)