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.
openapi: 3.1.0
info:
title: FullStory Webhooks 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/
externalDocs:
description: FullStory Webhooks API Documentation
url: https://developer.fullstory.com/destinations/v1/webhooks/getting-started/
servers:
- url: https://api.fullstory.com
description: FullStory Production API Server
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.
- name: Event Types
description: >-
List available webhook event types that can be configured for endpoints.
Some event types require subcategories and may be limited by plan.
security:
- basicAuth: []
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'
/webhooks/v1/event_types:
get:
operationId: listEventTypes
summary: List available webhook event types
description: >-
Returns the list of all available event types that can be configured
for webhook endpoints. Some event types may not be returned if your
FullStory plan does not support them. Event types that have
subcategories require a subcategory to be specified when creating
an endpoint.
tags:
- Event Types
responses:
'200':
description: List of event types retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/EventTypeList'
'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'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
API key passed in the Authorization header using Basic authentication.
Admin or Architect level keys are required.
parameters:
EndpointIdPath:
name: endpointId
in: path
required: true
description: >-
The unique identifier of the webhook endpoint
schema:
type: string
schemas:
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'
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
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'
EventType:
type: object
description: >-
A webhook event type available in FullStory
properties:
eventName:
type: string
description: >-
The name of the event type
description:
type: string
description: >-
Human-readable description of the event type
hasSubcategories:
type: boolean
description: >-
Whether this event type requires a subcategory when configuring
an endpoint
EventTypeList:
type: object
description: >-
List of available webhook event types
properties:
eventTypes:
type: array
description: >-
Array of available event types
items:
$ref: '#/components/schemas/EventType'
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