Orb Webhook endpoint API

openapi: 3.2.0
info:
  title: Reference Webhook endpoint API
  description: 'Orb''s API is built with the following principles in mind:


    1. **Predictable developer experience**: Where applicable, the Orb API uses industry-standard patterns such as

    cursor-based pagination and standardized error output. To help with debugging in critical API

    actions, the API always strives to provide detailed and actionable error messages. Aliases

    such as external customer IDs aid in fast integration times.

    2. **Reliably real time**: Orb''s event-based APIs, such as event ingestion are designed to handle extremely high

    throughput and scale with concurrent load. Orb also provides a real-time event-level credits

    ledger and a highly performant webhooks architecture.

    3. **Flexibility at the forefront**: Features like timezone localization and the ability to amend historical usage

    show the flexible nature of the platform.


    You can download the latest OpenAPI spec here - pass `?version=3.0` for an

    OpenAPI 3.0-compatible spec.'
  contact:
    name: Orb, Inc.
    url: https://www.withorb.com/
    email: team@withorb.com
  version: '1.0'
servers:
- url: https://api.withorb.com/v1
  description: Production server
security:
- APIKeyAuth: []
tags:
- name: Webhook endpoint
  description: A webhook endpoint is an HTTPS URL that Orb sends webhook events to.
paths:
  /webhook_endpoints:
    get:
      tags:
      - Webhook endpoint
      summary: List webhook endpoints
      description: This endpoint returns the account's webhook endpoints, ordered starting from the most recently created.
      operationId: list-webhook-endpoints
      parameters:
      - required: false
        style: form
        schema:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Limit
          description: The number of items to fetch. Defaults to 20.
          default: 20
        name: limit
        in: query
      - required: false
        style: form
        schema:
          oneOf:
          - type: string
          - type: 'null'
          title: Cursor
          description: Cursor for pagination. This can be populated by the `next_cursor` value returned from the initial request.
        name: cursor
        in: query
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoints'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
    post:
      tags:
      - Webhook endpoint
      summary: Create webhook endpoint
      description: 'This endpoint creates a webhook endpoint and returns the secret used to sign its webhook events. The secret

        isn''t returned by any other endpoint. An account can have at most 20 webhook endpoints by default.'
      operationId: create-webhook-endpoint
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewWebhookEndpoint'
        required: true
      responses:
        '201':
          description: Created
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpointWithSecret'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
  /webhook_endpoints/{webhook_endpoint_id}:
    get:
      tags:
      - Webhook endpoint
      summary: Fetch webhook endpoint
      description: This endpoint returns a webhook endpoint identified by its ID.
      operationId: fetch-webhook-endpoint
      parameters:
      - required: true
        style: simple
        schema:
          type: string
        name: webhook_endpoint_id
        in: path
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
    put:
      tags:
      - Webhook endpoint
      summary: Update webhook endpoint
      description: This endpoint updates a webhook endpoint's URL or the event types sent to it.
      operationId: update-webhook-endpoint
      parameters:
      - required: true
        style: simple
        schema:
          type: string
        name: webhook_endpoint_id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EditWebhookEndpoint'
        required: true
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
    delete:
      tags:
      - Webhook endpoint
      summary: Delete webhook endpoint
      description: This endpoint deletes a webhook endpoint. Orb stops sending webhook events to it immediately.
      operationId: delete-webhook-endpoint
      parameters:
      - required: true
        style: simple
        schema:
          type: string
        name: webhook_endpoint_id
        in: path
      responses:
        '204':
          description: No Content
          headers: {}
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
  /webhook_endpoints/{webhook_endpoint_id}/disable:
    post:
      tags:
      - Webhook endpoint
      summary: Disable webhook endpoint
      description: This endpoint disables a webhook endpoint, so Orb stops sending webhook events to it until it is enabled again.
      operationId: disable-webhook-endpoint
      parameters:
      - required: true
        style: simple
        schema:
          type: string
        name: webhook_endpoint_id
        in: path
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
  /webhook_endpoints/{webhook_endpoint_id}/enable:
    post:
      tags:
      - Webhook endpoint
      summary: Enable webhook endpoint
      description: This endpoint enables a webhook endpoint, so Orb resumes sending webhook events to it.
      operationId: enable-webhook-endpoint
      parameters:
      - required: true
        style: simple
        schema:
          type: string
        name: webhook_endpoint_id
        in: path
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEndpoint'
        '400':
          description: Bad Request
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
        '401':
          description: Unauthorized
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401Error'
        '404':
          description: Not Found
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404Error'
        '409':
          description: Conflict
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/409Error'
        '413':
          description: Content Too Large
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/413Error'
        '429':
          description: Too Many Requests
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/429Error'
        '500':
          description: Internal Server Error
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500Error'
components:
  schemas:
    RequestTooLargeError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#413-request-too-large
          title: Type
        status:
          type: integer
          enum:
          - 413
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: RequestTooLargeError
    401Error:
      $ref: '#/components/schemas/AuthorizationError'
      title: 401Error
    AuthorizationError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#401-authentication-error
          title: Type
        status:
          type: integer
          enum:
          - 401
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: AuthorizationError
    WebhookEndpoints:
      properties:
        data:
          items:
            $ref: '#/components/schemas/WebhookEndpoint'
          type: array
          title: Data
        pagination_metadata:
          $ref: '#/components/schemas/PaginationMetadata'
      type: object
      required:
      - data
      - pagination_metadata
      title: WebhookEndpoints
    429Error:
      $ref: '#/components/schemas/TooManyRequests'
      title: 429Error
    FeatureNotAvailableError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#404-feature-not-available
          title: Type
        status:
          type: integer
          enum:
          - 400
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: FeatureNotAvailableError
    413Error:
      oneOf:
      - $ref: '#/components/schemas/RequestTooLargeError'
      - $ref: '#/components/schemas/ResourceTooLargeError'
      - $ref: '#/components/schemas/TooManyResultsError'
    IdempotencyRequestMismatch:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#409-resource-conflict
          title: Type
        status:
          type: integer
          enum:
          - 409
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: IdempotencyRequestMismatch
    TooManyRequests:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#429-too-many-requests
          title: Type
        status:
          type: integer
          enum:
          - 429
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: TooManyRequests
    ResourceTooLargeError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#413-resource-too-large
          title: Type
        status:
          type: integer
          enum:
          - 413
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: ResourceTooLargeError
    EditWebhookEndpoint:
      properties:
        url:
          oneOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Url
          description: The HTTPS URL that Orb sends webhook events to.
        enabled_event_types:
          oneOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Enabled Event Types
          description: The webhook event types to send to this endpoint. Null sends all event types; omit to leave them unchanged.
        payload_style:
          oneOf:
          - type: string
            enum:
            - expanded
            - standard
          - type: 'null'
          title: Payload Style
          description: The payload style of the webhook events sent to this endpoint. Applies to events created after the change; omit to leave it unchanged.
      additionalProperties: false
      type: object
      title: EditWebhookEndpoint
    409Error:
      $ref: '#/components/schemas/IdempotencyRequestMismatch'
      title: 409Error
    TooManyResultsError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#413-too-many-results
          title: Type
        status:
          type: integer
          enum:
          - 413
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: TooManyResultsError
    PaginationMetadata:
      properties:
        has_more:
          type: boolean
          title: Has More
        next_cursor:
          oneOf:
          - type: string
          - type: 'null'
          title: Next Cursor
      type: object
      required:
      - has_more
      - next_cursor
      title: PaginationMetadata
    WebhookEndpointWithSecret:
      properties:
        id:
          type: string
          title: Id
          description: The Orb-assigned unique identifier for the webhook endpoint.
        url:
          type: string
          title: Url
          description: The HTTPS URL that Orb sends webhook events to.
        enabled:
          type: boolean
          title: Enabled
          description: Whether Orb sends webhook events to this endpoint.
        enabled_event_types:
          oneOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Enabled Event Types
          description: The webhook event types sent to this endpoint. If null, all event types are sent.
        payload_style:
          type: string
          enum:
          - expanded
          - standard
          title: Payload Style
          description: The payload style of the webhook events sent to this endpoint. `standard` payloads include each object's own fields and references to related objects, without invoice line items or subscription price intervals. `expanded` payloads include every object fully expanded.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The time the webhook endpoint was created.
        secret:
          type: string
          title: Secret
          description: The secret used to sign the webhook events sent to this endpoint. Only returned when the endpoint is created.
      type: object
      required:
      - id
      - url
      - enabled
      - enabled_event_types
      - payload_style
      - created_at
      - secret
      title: WebhookEndpointWithSecret
      description: A newly created webhook endpoint, along with the secret used to sign its webhook events.
    ResourceNotFoundError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#404-resource-not-found
          title: Type
        status:
          type: integer
          enum:
          - 404
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          type: string
          title: Title
      type: object
      required:
      - type
      - status
      - title
      title: ResourceNotFoundError
    404Error:
      oneOf:
      - $ref: '#/components/schemas/FeatureNotAvailableError'
      - $ref: '#/components/schemas/ResourceNotFoundError'
      - $ref: '#/components/schemas/URLNotFound'
    ServerError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#500-internal-server-error
          title: Type
        status:
          type: integer
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: ServerError
    URLNotFound:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#404-url-not-found
          title: Type
        status:
          type: integer
          enum:
          - 404
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: URLNotFound
    DuplicateResourceCreationError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation
          title: Type
        status:
          type: integer
          enum:
          - 400
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: DuplicateResourceCreationError
    WebhookEndpoint:
      properties:
        id:
          type: string
          title: Id
          description: The Orb-assigned unique identifier for the webhook endpoint.
        url:
          type: string
          title: Url
          description: The HTTPS URL that Orb sends webhook events to.
        enabled:
          type: boolean
          title: Enabled
          description: Whether Orb sends webhook events to this endpoint.
        enabled_event_types:
          oneOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Enabled Event Types
          description: The webhook event types sent to this endpoint. If null, all event types are sent.
        payload_style:
          type: string
          enum:
          - expanded
          - standard
          title: Payload Style
          description: The payload style of the webhook events sent to this endpoint. `standard` payloads include each object's own fields and references to related objects, without invoice line items or subscription price intervals. `expanded` payloads include every object fully expanded.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: The time the webhook endpoint was created.
      type: object
      required:
      - id
      - url
      - enabled
      - enabled_event_types
      - payload_style
      - created_at
      title: WebhookEndpoint
      description: A webhook endpoint is an HTTPS URL that Orb sends [webhook events](/integrations-and-exports/webhooks) to.
    RequestValidationError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#400-request-validation-errors
          title: Type
        status:
          type: integer
          enum:
          - 400
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
        validation_errors:
          items: {}
          type: array
          title: Validation Errors
      type: object
      required:
      - type
      - status
      - validation_errors
      title: RequestValidationError
    NewWebhookEndpoint:
      properties:
        url:
          type: string
          maxLength: 2048
          title: Url
          description: The HTTPS URL that Orb sends webhook events to.
        enabled_event_types:
          oneOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Enabled Event Types
          description: The webhook event types to send to this endpoint. If omitted or null, all event types are sent.
        payload_style:
          oneOf:
          - type: string
            enum:
            - expanded
            - standard
          - type: 'null'
          title: Payload Style
          description: The payload style of the webhook events sent to this endpoint. If omitted or null, the account's default style is used.
      additionalProperties: false
      type: object
      required:
      - url
      title: NewWebhookEndpoint
    400Error:
      oneOf:
      - $ref: '#/components/schemas/ConstraintViolationError'
      - $ref: '#/components/schemas/DuplicateResourceCreationError'
      - $ref: '#/components/schemas/RequestValidationError'
    ConstraintViolationError:
      properties:
        type:
          type: string
          enum:
          - https://docs.withorb.com/reference/error-responses#400-constraint-violation
          title: Type
        status:
          type: integer
          enum:
          - 400
          title: Status
        detail:
          oneOf:
          - type: string
          - type: 'null'
          title: Detail
        title:
          oneOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - type
      - status
      title: ConstraintViolationError
    500Error:
      $ref: '#/components/schemas/ServerError'
      title: 500Error
  securitySchemes:
    APIKeyAuth:
      type: http
      description: API Keys can be issued in the Orb's web application.
      scheme: bearer
x-provenance:
  method: harvested
  publisher: Orb
  source: https://docs.withorb.com/api-reference/orb-openapi.json
  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)