openapi: 3.1.0 info: title: Webhooks API version: 1.0.0 description: >- # Webhooks API ## Overview The Alpha Webhooks API allows you to register endpoints that will receive real-time notifications when Caliper events are processed by our system. This enables your application to react immediately to learning events without the need for polling or direct database access. # Authentication ## Guide Most endpoints require authentication using the `Authorization: Bearer ` header. The token can be obtained with: ``` curl -X POST https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=&client_secret=" ``` Use the correct IDP server depending on the environment you're using. IDP Server for this environment: ```text https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com ``` Reach out to the platform team to get a client/secret pair for your application. servers: - url: https://caliper.alpha-1edtech.ai description: Webhooks API tags: - name: Webhook Filters description: >- These are the endpoints to use when creating, updating, and deleting webhook filters - name: Webhooks description: >- These are the endpoints to use when creating, updating, and deleting webhooks security: - OAuth2: [] paths: /webhook-filters/: get: tags: - Webhook Filters summary: Get all webhook filters description: Returns all webhook filters responses: '200': description: Webhook filters retrieved successfully content: application/json: schema: type: object properties: filters: type: array items: type: object properties: webhookId: type: string description: >- The unique identifier for the webhook, in UUID format example: 123e4567-e89b-12d3-a456-426614174000 filterKey: type: string description: The key to filter on example: sensor filterValue: type: string description: The value to filter on example: sensor123 filterType: type: string enum: &ref_0 - string - number - boolean description: The type of the filter value example: string filterOperation: type: string enum: &ref_1 - eq - neq - gt - gte - lt - lte - contains - notContains - in - notIn - startsWith - endsWith - regexp description: The operation to perform on the filter value example: eq active: type: boolean description: Whether the filter is active example: true createdAt: type: string description: The date and time the filter was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the filter was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the filter was deleted example: 2021-01-01T00:00:00.000Z required: - webhookId - filterKey - filterValue - filterType - filterOperation - active - createdAt - updatedAt - deletedAt required: - filters post: tags: - Webhook Filters summary: Create a webhook filter description: Creates a new webhook filter requestBody: description: The webhook filter to create required: true content: application/json: schema: type: object properties: webhookId: type: string description: The unique identifier for the webhook, in UUID format example: 123e4567-e89b-12d3-a456-426614174000 filterKey: type: string description: The key to filter on example: sensor filterValue: type: string description: The value to filter on example: sensor123 filterType: type: string enum: *ref_0 description: The type of the filter value example: string filterOperation: type: string enum: *ref_1 description: The operation to perform on the filter value example: eq active: type: boolean description: Whether the filter is active example: true required: - webhookId - filterKey - filterValue - filterType - filterOperation - active responses: '201': description: Webhook filter created successfully content: application/json: schema: type: object properties: filter: type: object properties: webhookId: type: string description: The unique identifier for the webhook, in UUID format example: 123e4567-e89b-12d3-a456-426614174000 filterKey: type: string description: The key to filter on example: sensor filterValue: type: string description: The value to filter on example: sensor123 filterType: type: string enum: *ref_0 description: The type of the filter value example: string filterOperation: type: string enum: *ref_1 description: The operation to perform on the filter value example: eq active: type: boolean description: Whether the filter is active example: true createdAt: type: string description: The date and time the filter was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the filter was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the filter was deleted example: 2021-01-01T00:00:00.000Z required: - webhookId - filterKey - filterValue - filterType - filterOperation - active - createdAt - updatedAt - deletedAt required: - filter '400': description: Invalid webhook filter data content: application/json: schema: type: object properties: status: type: string const: error message: type: string errors: {} required: - status - message /webhook-filters/{id}: get: tags: - Webhook Filters summary: Get a webhook filter by ID description: Returns a specific webhook filter by ID parameters: - name: id in: path required: true schema: type: string responses: '200': description: Webhook filter retrieved successfully content: application/json: schema: type: object properties: filter: type: object properties: webhookId: type: string description: The unique identifier for the webhook, in UUID format example: 123e4567-e89b-12d3-a456-426614174000 filterKey: type: string description: The key to filter on example: sensor filterValue: type: string description: The value to filter on example: sensor123 filterType: type: string enum: *ref_0 description: The type of the filter value example: string filterOperation: type: string enum: *ref_1 description: The operation to perform on the filter value example: eq active: type: boolean description: Whether the filter is active example: true createdAt: type: string description: The date and time the filter was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the filter was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the filter was deleted example: 2021-01-01T00:00:00.000Z required: - webhookId - filterKey - filterValue - filterType - filterOperation - active - createdAt - updatedAt - deletedAt required: - filter delete: tags: - Webhook Filters summary: Delete a webhook filter description: Deletes a webhook filter by ID parameters: - name: id in: path required: true schema: type: string responses: '200': description: Webhook filter deleted successfully content: application/json: schema: type: object properties: status: type: string const: success message: type: string errors: {} required: - status - message /webhook-filters/webhook/{webhookId}: get: tags: - Webhook Filters summary: Get webhook filters by webhook ID description: Returns all filters for a specific webhook parameters: - name: webhookId in: path required: true schema: type: string responses: '200': description: Webhook filters retrieved successfully content: application/json: schema: type: object properties: filters: type: array items: type: object properties: webhookId: type: string description: >- The unique identifier for the webhook, in UUID format example: 123e4567-e89b-12d3-a456-426614174000 filterKey: type: string description: The key to filter on example: sensor filterValue: type: string description: The value to filter on example: sensor123 filterType: type: string enum: *ref_0 description: The type of the filter value example: string filterOperation: type: string enum: *ref_1 description: The operation to perform on the filter value example: eq active: type: boolean description: Whether the filter is active example: true createdAt: type: string description: The date and time the filter was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the filter was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the filter was deleted example: 2021-01-01T00:00:00.000Z required: - webhookId - filterKey - filterValue - filterType - filterOperation - active - createdAt - updatedAt - deletedAt required: - filters /webhooks/: get: tags: - Webhooks summary: Get for a sensor description: Returns all webhooks for a specific sensor parameters: - name: sensor in: query required: false schema: type: string responses: '200': description: Webhooks retrieved successfully content: application/json: schema: type: object properties: webhooks: type: array items: type: object properties: id: type: string description: The unique identifier for the webhook example: 123e4567-e89b-12d3-a456-426614174000 sensor: type: - string - 'null' description: The sensor that the webhook is associated with example: sensor123 name: type: string description: The name of the webhook example: My Webhook description: type: - string - 'null' description: The description of the webhook example: >- This webhook is used to send data to the example.com/webhook targetUrl: type: string description: The URL that the webhook will send the data to example: https://example.com/webhook secret: type: string description: >- The secret that the webhook will use to authenticate the data example: secret123 active: type: boolean description: Whether the webhook is active example: true createdAt: type: - string - 'null' description: The date and time the webhook was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the webhook was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the webhook was deleted example: 2021-01-01T00:00:00.000Z required: - id - name - description - targetUrl - secret - active - createdAt - updatedAt - deletedAt required: - webhooks post: tags: - Webhooks summary: Create a webhook description: Creates a new webhook requestBody: description: The webhook to create required: true content: application/json: schema: type: object properties: sensor: type: - string - 'null' description: The sensor that the webhook is associated with example: sensor123 name: type: string description: The name of the webhook example: My Webhook description: type: - string - 'null' description: The description of the webhook example: This webhook is used to send data to the example.com/webhook targetUrl: type: string description: The URL that the webhook will send the data to example: https://example.com/webhook secret: type: string description: >- The secret that the webhook will use to authenticate the data example: secret123 active: type: boolean description: Whether the webhook is active example: true required: - name - description - targetUrl - secret - active responses: '201': description: Webhook created successfully content: application/json: schema: type: object properties: webhook: type: object properties: id: type: string description: The unique identifier for the webhook example: 123e4567-e89b-12d3-a456-426614174000 sensor: type: - string - 'null' description: The sensor that the webhook is associated with example: sensor123 name: type: string description: The name of the webhook example: My Webhook description: type: - string - 'null' description: The description of the webhook example: >- This webhook is used to send data to the example.com/webhook targetUrl: type: string description: The URL that the webhook will send the data to example: https://example.com/webhook secret: type: string description: >- The secret that the webhook will use to authenticate the data example: secret123 active: type: boolean description: Whether the webhook is active example: true createdAt: type: - string - 'null' description: The date and time the webhook was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the webhook was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the webhook was deleted example: 2021-01-01T00:00:00.000Z required: - id - name - description - targetUrl - secret - active - createdAt - updatedAt - deletedAt required: - webhook '400': description: Invalid webhook data content: application/json: schema: type: object properties: error: type: string description: The error message example: An error occurred details: type: array items: type: object properties: code: type: string description: The code of the error example: invalid_type expected: type: string description: The expected value example: string received: type: string description: The received value example: undefined path: type: array items: type: string description: The path of the error example: &ref_2 - sensor message: type: string description: The message of the error example: Required required: - code - expected - received - path - message required: - error - details /webhooks/{id}: get: tags: - Webhooks summary: Get a specific webhook description: Returns a specific webhook by ID responses: '200': description: Webhook retrieved successfully content: application/json: schema: type: object properties: webhook: type: object properties: id: type: string description: The unique identifier for the webhook example: 123e4567-e89b-12d3-a456-426614174000 sensor: type: - string - 'null' description: The sensor that the webhook is associated with example: sensor123 name: type: string description: The name of the webhook example: My Webhook description: type: - string - 'null' description: The description of the webhook example: >- This webhook is used to send data to the example.com/webhook targetUrl: type: string description: The URL that the webhook will send the data to example: https://example.com/webhook secret: type: string description: >- The secret that the webhook will use to authenticate the data example: secret123 active: type: boolean description: Whether the webhook is active example: true createdAt: type: - string - 'null' description: The date and time the webhook was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the webhook was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the webhook was deleted example: 2021-01-01T00:00:00.000Z required: - id - name - description - targetUrl - secret - active - createdAt - updatedAt - deletedAt required: - webhook put: tags: - Webhooks summary: Update a webhook description: Updates an existing webhook by ID requestBody: description: The webhook to update required: true content: application/json: schema: type: object properties: sensor: type: - string - 'null' description: The sensor that the webhook is associated with example: sensor123 name: type: string description: The name of the webhook example: My Webhook description: type: - string - 'null' description: The description of the webhook example: This webhook is used to send data to the example.com/webhook targetUrl: type: string description: The URL that the webhook will send the data to example: https://example.com/webhook secret: type: string description: >- The secret that the webhook will use to authenticate the data example: secret123 active: type: boolean description: Whether the webhook is active example: true required: - name - description - targetUrl - secret - active responses: '200': description: Webhook updated successfully content: application/json: schema: type: object properties: webhook: type: object properties: id: type: string description: The unique identifier for the webhook example: 123e4567-e89b-12d3-a456-426614174000 sensor: type: - string - 'null' description: The sensor that the webhook is associated with example: sensor123 name: type: string description: The name of the webhook example: My Webhook description: type: - string - 'null' description: The description of the webhook example: >- This webhook is used to send data to the example.com/webhook targetUrl: type: string description: The URL that the webhook will send the data to example: https://example.com/webhook secret: type: string description: >- The secret that the webhook will use to authenticate the data example: secret123 active: type: boolean description: Whether the webhook is active example: true createdAt: type: - string - 'null' description: The date and time the webhook was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the webhook was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the webhook was deleted example: 2021-01-01T00:00:00.000Z required: - id - name - description - targetUrl - secret - active - createdAt - updatedAt - deletedAt required: - webhook '400': description: Invalid webhook data content: application/json: schema: type: object properties: error: type: string description: The error message example: An error occurred details: type: array items: type: object properties: code: type: string description: The code of the error example: invalid_type expected: type: string description: The expected value example: string received: type: string description: The received value example: undefined path: type: array items: type: string description: The path of the error example: *ref_2 message: type: string description: The message of the error example: Required required: - code - expected - received - path - message required: - error - details delete: tags: - Webhooks summary: Delete a webhook description: Deletes a webhook by ID responses: '200': description: Webhook deleted successfully content: application/json: schema: type: object properties: status: type: string const: success message: type: string errors: {} required: - status - message /webhooks/:id/activate: put: tags: - Webhooks summary: Activate a webhook description: Activates a webhook by ID responses: '200': description: Webhook activated successfully content: application/json: schema: type: object properties: webhook: type: object properties: id: type: string description: The unique identifier for the webhook example: 123e4567-e89b-12d3-a456-426614174000 sensor: type: - string - 'null' description: The sensor that the webhook is associated with example: sensor123 name: type: string description: The name of the webhook example: My Webhook description: type: - string - 'null' description: The description of the webhook example: >- This webhook is used to send data to the example.com/webhook targetUrl: type: string description: The URL that the webhook will send the data to example: https://example.com/webhook secret: type: string description: >- The secret that the webhook will use to authenticate the data example: secret123 active: type: boolean description: Whether the webhook is active example: true createdAt: type: - string - 'null' description: The date and time the webhook was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the webhook was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the webhook was deleted example: 2021-01-01T00:00:00.000Z required: - id - name - description - targetUrl - secret - active - createdAt - updatedAt - deletedAt required: - webhook /webhooks/:id/deactivate: put: tags: - Webhooks summary: Deactivate a webhook description: Deactivates a webhook by ID responses: '200': description: Webhook deactivated successfully content: application/json: schema: type: object properties: webhook: type: object properties: id: type: string description: The unique identifier for the webhook example: 123e4567-e89b-12d3-a456-426614174000 sensor: type: - string - 'null' description: The sensor that the webhook is associated with example: sensor123 name: type: string description: The name of the webhook example: My Webhook description: type: - string - 'null' description: The description of the webhook example: >- This webhook is used to send data to the example.com/webhook targetUrl: type: string description: The URL that the webhook will send the data to example: https://example.com/webhook secret: type: string description: >- The secret that the webhook will use to authenticate the data example: secret123 active: type: boolean description: Whether the webhook is active example: true createdAt: type: - string - 'null' description: The date and time the webhook was created example: 2021-01-01T00:00:00.000Z updatedAt: type: string description: The date and time the webhook was last updated example: 2021-01-01T00:00:00.000Z deletedAt: type: - string - 'null' description: The date and time the webhook was deleted example: 2021-01-01T00:00:00.000Z required: - id - name - description - targetUrl - secret - active - createdAt - updatedAt - deletedAt required: - webhook components: securitySchemes: MCP: type: oauth2 flows: authorizationCode: authorizationUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/authorize tokenUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token scopes: https://purl.imsglobal.org/spec/caliper/v1p1/scope/webhook.readonly: Webhook readonly scope (can read webhooks) OAuth2: type: oauth2 flows: clientCredentials: scopes: https://purl.imsglobal.org/spec/caliper/v1p1/scope/admin: Admin scope (can call all endpoints) https://purl.imsglobal.org/spec/caliper/v1p1/scope/webhook.create: Webhook create scope (can create and update webhooks) https://purl.imsglobal.org/spec/caliper/v1p1/scope/webhook.readonly: Webhook readonly scope (can read webhooks) https://purl.imsglobal.org/spec/caliper/v1p1/scope/event.create: Event create scope (can create events) tokenUrl: >- https://prod-beyond-timeback-api-2-idp.auth.us-east-1.amazoncognito.com/oauth2/token