FullStory Endpoints API

openapi: 3.2.0
info:
  title: FullStory Webhooks Endpoints API
  description: The FullStory Webhooks API enables developers to create, update, retrieve, and manage webhook endpoints that receive real-time notifications from FullStory. Supported event types include segment creation, segment threshold alerts, and custom event notifications. Webhooks allow event-driven integrations that respond immediately to behavioral signals detected by FullStory, eliminating the need for polling and enabling automated workflows based on user activity patterns.
  version: '1.0'
  contact:
    name: FullStory Support
    url: https://help.fullstory.com/
  termsOfService: https://www.fullstory.com/legal/terms-and-conditions/
servers:
- url: https://api.fullstory.com
  description: FullStory Production API Server
security:
- basicAuth: []
tags:
- name: Endpoints
  description: Create, retrieve, update, and delete webhook endpoints that receive real-time notifications from FullStory. Each endpoint has a destination URL, configured event types, signing secret, and enabled status.
paths:
  /webhooks/v1/endpoints:
    post:
      operationId: createEndpoint
      summary: Create a webhook endpoint
      description: Creates a new webhook endpoint with the given properties, including the destination URL and the event types it should receive. Some event types require a subcategory property. Returns the created endpoint details including its ID and signing secret.
      tags:
      - Endpoints
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEndpointRequest'
      responses:
        '200':
          description: Webhook endpoint created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          description: Invalid input provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listEndpoints
      summary: List webhook endpoints
      description: Pages through all configured webhook endpoints with pagination support. Returns endpoint details including ID, URL, configured event types, and enabled status.
      tags:
      - Endpoints
      responses:
        '200':
          description: List of webhook endpoints retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EndpointList'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /webhooks/v1/endpoints/{endpointId}:
    get:
      operationId: getEndpoint
      summary: Get a webhook endpoint
      description: Retrieves endpoint details corresponding to the provided endpoint ID, including the destination URL, configured event types, signing secret, and enabled status.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/EndpointIdPath'
      responses:
        '200':
          description: Webhook endpoint retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Endpoint not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateEndpoint
      summary: Update a webhook endpoint
      description: Updates an existing webhook endpoint. Can be used to change the destination URL, configured events, signing secret, and the enabled status of the endpoint.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/EndpointIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEndpointRequest'
      responses:
        '200':
          description: Webhook endpoint updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Endpoint'
        '400':
          description: Invalid input provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Endpoint not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteEndpoint
      summary: Delete a webhook endpoint
      description: Permanently deletes the webhook endpoint specified by the endpoint ID. The endpoint will no longer receive any event notifications after deletion.
      tags:
      - Endpoints
      parameters:
      - $ref: '#/components/parameters/EndpointIdPath'
      responses:
        '200':
          description: Webhook endpoint deleted successfully
        '401':
          description: Unauthorized - invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Endpoint not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    EndpointIdPath:
      name: endpointId
      in: path
      required: true
      description: The unique identifier of the webhook endpoint
      schema:
        type: string
  schemas:
    UpdateEndpointRequest:
      type: object
      description: Request body for updating an existing webhook endpoint
      properties:
        url:
          type: string
          format: uri
          description: The new destination URL for webhook events
        events:
          type: array
          description: Updated list of event types for this endpoint
          items:
            $ref: '#/components/schemas/EventTypeConfig'
        signingSecret:
          type: string
          description: Updated signing secret for verifying webhook payloads
        enabled:
          type: boolean
          description: Whether the endpoint is enabled and receiving events
    EventTypeConfig:
      type: object
      required:
      - eventName
      description: Configuration for a specific event type on a webhook endpoint
      properties:
        eventName:
          type: string
          description: The name of the event type
          enum:
          - segment.created
          - segment.trend.alert
          - recording.event.custom
          - note.created
        subcategory:
          type: string
          description: Required subcategory for event types that require one, such as specifying which custom event to listen for
    Error:
      type: object
      description: Standard error response from the FullStory API
      properties:
        code:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Human-readable error message
    CreateEndpointRequest:
      type: object
      required:
      - url
      - events
      description: Request body for creating a new webhook endpoint
      properties:
        url:
          type: string
          format: uri
          description: The URL that will receive webhook event notifications
        events:
          type: array
          description: The types of events this endpoint should receive
          items:
            $ref: '#/components/schemas/EventTypeConfig'
    Endpoint:
      type: object
      description: A configured webhook endpoint in FullStory
      properties:
        id:
          type: string
          description: Unique identifier for the webhook endpoint
        url:
          type: string
          format: uri
          description: The destination URL receiving webhook events
        events:
          type: array
          description: The event types configured for this endpoint
          items:
            $ref: '#/components/schemas/EventTypeConfig'
        signingSecret:
          type: string
          description: Secret used to sign webhook payloads for verification
        enabled:
          type: boolean
          description: Whether the endpoint is actively receiving events
        createdAt:
          type: string
          format: date-time
          description: Timestamp when the endpoint was created
    EndpointList:
      type: object
      description: List of webhook endpoints
      properties:
        endpoints:
          type: array
          description: Array of configured webhook endpoints
          items:
            $ref: '#/components/schemas/Endpoint'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: API key passed in the Authorization header using Basic authentication. Admin or Architect level keys are required.
externalDocs:
  description: FullStory Webhooks API Documentation
  url: https://developer.fullstory.com/destinations/v1/webhooks/getting-started/