openapi: 3.1.0 info: version: 1.3.0 title: Ethena Learner Training Campaigns Webhooks API termsOfService: https://app.goethena.com/legal-and-privacy contact: name: Contact support email: support@goethena.com x-logo: url: ./ethena-logo.png altText: Ethena logo description: 'The Ethena API allows you to view and manage learners and training information. # Accessing the API In order to get access to our API please work with your sales representative to get an API key provisioned and shared with you. Webhooks are not enabled by default, please work with your sales representative to have them enabled if you need them. # Changelog - **v1.0.0** - Initial release of the API, including learners, training campaigns, learner training campaigns, and learner training modules. - **v1.1.0** - Added webhooks operations and support for learner training campaign completed webhook. - **v1.2.0** - Remove separate language region property on learner and support Unicode Common Locale Data Repository language formats. - **v1.3.0** - Added filter parameters for learners (email, name), learner training modules (learnerStatus, trainingCampaignStatus), and learner training campaigns (learnerStatus, trainingCampaignStatus). Added training campaign status field to training campaigns.' servers: - url: https://api.goethena.com tags: - name: Webhooks description: "Webhooks are not enabled by default, please work with your sales representative to have them enabled if you need them.\n\nOnce you have access, webhooks can be managed through the API. Currently, only the following webhooks are supported:\n - Learner Training Campaign Completed\n\n# Security\n\nRequests to the webhook URL include a header `X-Signature`, which contains a signature of the payload. This signature is generated using the secret key provided when the webhook was created.\n\n## Signature Verification \n\nTo verify the signature of incoming requests, you need the secret key for a webhook. This key can be retrieved by calling `GET /v1/webhooks/{id}` after webhook creation. The secret key is not returned in the create webhook response. This key is used to generate a signature of the payload and compare it with the `X-Signature` header in the request.\n\nThe signature is generated using the **HMAC SHA-256** algorithm. The **secret key** is used as the key, and the **request payload** is used as the data. The resulting HMAC is then converted into a hexadecimal string.\n\nFor example:\n\n```js\nconst crypto = require('crypto');\n\nconst signature = crypto\n .createHmac('sha256', secretKey) \n .update(JSON.stringify(payload))\n .digest('hex');\n```\n\nIn this example:\n\n1. `secretKey` is the secret key that can be retrieved by calling `GET /v1/webhooks/{id}` after webhook creation.\n1. `payload` is the data you receive in the webhook request (usually in JSON format).\n1. The `crypto.createHmac()` function creates a hash object, which uses the SHA-256 algorithm and the `secretKey` as the key.\n1. `update()` adds the stringified payload to the hash.\n1. `digest('hex')` generates the HMAC hash in hexadecimal format, which can be compared to the `X-Signature` header in the request.\n\n\n# Retry Policy\n\nWebhook requests will be attempted up to **three times**, with a retry interval of **five minutes**, before being considered failed.\n\nA **30-second request timeout** is enforced, meaning the webhook request must complete within 30 seconds. If the request exceeds this timeout, the attempt will be considered failed." paths: /v1/webhooks: get: tags: - Webhooks summary: Get webhooks description: Get all webhooks. operationId: getWebhooks security: - basic_auth: [] responses: '200': description: Success content: application/json: schema: allOf: - type: object properties: data: type: array items: type: object required: - id - type - url - secretKey properties: id: allOf: - description: The unique identifier of a webhook. type: string pattern: ^[a-zA-Z0-9]+$ example: wh123abc45 type: allOf: - description: The type of webhook. Currently, only one type, `LEARNER_TRAINING_CAMPAIGN_COMPLETED`, is supported. type: string enum: - LEARNER_TRAINING_CAMPAIGN_COMPLETED example: LEARNER_TRAINING_CAMPAIGN_COMPLETED url: allOf: - description: The url of the callback that will be triggered when the webhook is fired. type: string format: uri maxLength: 2048 example: https://{your-domain}.com/webhooks/ethena secretKey: allOf: - description: The generated secret key that is used to sign requests to the webhook url. type: string pattern: ^[a-f0-9]+$ example: a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd '400': description: Bad Request content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: &id001 - title properties: &id002 title: description: A short, human-readable summary of the problem type. type: string detail: description: A human-readable explanation specific to this occurrence of the problem. type: string invalid-params: description: An array of objects, each representing a parameter that was invalid. type: array items: type: object properties: name: type: string description: The name of the invalid parameter. reason: type: string description: The reason why the parameter is invalid. '401': description: Unauthorized content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id001 properties: *id002 '403': description: Forbidden content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id001 properties: *id002 post: tags: - Webhooks summary: Create a new webhook description: Create a new webhook. operationId: createWebhook security: - basic_auth: [] requestBody: description: Webhook to be created. required: true content: application/json: schema: type: object required: - url - type properties: url: allOf: - description: The url of the callback that will be triggered when the webhook is fired. type: string format: uri maxLength: 2048 example: https://{your-domain}.com/webhooks/ethena type: allOf: - description: The type of webhook. Currently, only one type, `LEARNER_TRAINING_CAMPAIGN_COMPLETED`, is supported. type: string enum: - LEARNER_TRAINING_CAMPAIGN_COMPLETED example: LEARNER_TRAINING_CAMPAIGN_COMPLETED responses: '200': description: Created content: application/json: schema: description: The unique identifier of a webhook. type: string pattern: ^[a-zA-Z0-9]+$ example: wh123abc45 '400': description: Bad Request content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: &id003 - title properties: &id004 title: description: A short, human-readable summary of the problem type. type: string detail: description: A human-readable explanation specific to this occurrence of the problem. type: string invalid-params: description: An array of objects, each representing a parameter that was invalid. type: array items: type: object properties: name: type: string description: The name of the invalid parameter. reason: type: string description: The reason why the parameter is invalid. '401': description: Unauthorized content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id003 properties: *id004 '403': description: Forbidden content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id003 properties: *id004 /v1/webhooks/{id}: get: tags: - Webhooks summary: Get a webhook by id description: Get a webhook. operationId: getWebhookById parameters: - name: id in: path required: true schema: description: The unique identifier of a webhook. type: string pattern: ^[a-zA-Z0-9]+$ example: wh123abc45 security: - basic_auth: [] responses: '200': description: Success content: application/json: schema: allOf: - type: object required: - id - type - url - secretKey properties: id: allOf: - description: The unique identifier of a webhook. type: string pattern: ^[a-zA-Z0-9]+$ example: wh123abc45 type: allOf: - description: The type of webhook. Currently, only one type, `LEARNER_TRAINING_CAMPAIGN_COMPLETED`, is supported. type: string enum: - LEARNER_TRAINING_CAMPAIGN_COMPLETED example: LEARNER_TRAINING_CAMPAIGN_COMPLETED url: allOf: - description: The url of the callback that will be triggered when the webhook is fired. type: string format: uri maxLength: 2048 example: https://{your-domain}.com/webhooks/ethena secretKey: allOf: - description: The generated secret key that is used to sign requests to the webhook url. type: string pattern: ^[a-f0-9]+$ example: a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd '400': description: Bad Request content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: &id005 - title properties: &id006 title: description: A short, human-readable summary of the problem type. type: string detail: description: A human-readable explanation specific to this occurrence of the problem. type: string invalid-params: description: An array of objects, each representing a parameter that was invalid. type: array items: type: object properties: name: type: string description: The name of the invalid parameter. reason: type: string description: The reason why the parameter is invalid. '401': description: Unauthorized content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id005 properties: *id006 '403': description: Forbidden content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id005 properties: *id006 '404': description: Not Found content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id005 properties: *id006 patch: tags: - Webhooks summary: Update webhook by id description: Update a webhook. operationId: patchWebhookById parameters: - name: id in: path required: true schema: description: The unique identifier of a webhook. type: string pattern: ^[a-zA-Z0-9]+$ example: wh123abc45 security: - basic_auth: [] requestBody: description: Webhook properties to be updated required: true content: application/json: schema: type: object properties: url: allOf: - description: The url of the callback that will be triggered when the webhook is fired. type: string format: uri maxLength: 2048 example: https://{your-domain}.com/webhooks/ethena type: allOf: - description: The type of webhook. Currently, only one type, `LEARNER_TRAINING_CAMPAIGN_COMPLETED`, is supported. type: string enum: - LEARNER_TRAINING_CAMPAIGN_COMPLETED example: LEARNER_TRAINING_CAMPAIGN_COMPLETED responses: '204': description: No Content '400': description: Bad Request content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: &id007 - title properties: &id008 title: description: A short, human-readable summary of the problem type. type: string detail: description: A human-readable explanation specific to this occurrence of the problem. type: string invalid-params: description: An array of objects, each representing a parameter that was invalid. type: array items: type: object properties: name: type: string description: The name of the invalid parameter. reason: type: string description: The reason why the parameter is invalid. '401': description: Unauthorized content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id007 properties: *id008 '403': description: Forbidden content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id007 properties: *id008 '404': description: Not Found content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id007 properties: *id008 delete: tags: - Webhooks summary: Delete a webhook by id description: Delete a webhook. This is a **hard delete**. The deleted webhook will no longer be accessible via the API. This operation is irreversible. If a webhook is deleted by mistake, a new webhook will need to be created. operationId: deleteWebhookById parameters: - name: id in: path required: true schema: description: The unique identifier of a webhook. type: string pattern: ^[a-zA-Z0-9]+$ example: wh123abc45 security: - basic_auth: [] responses: '204': description: No Content '400': description: Bad Request content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: &id009 - title properties: &id010 title: description: A short, human-readable summary of the problem type. type: string detail: description: A human-readable explanation specific to this occurrence of the problem. type: string invalid-params: description: An array of objects, each representing a parameter that was invalid. type: array items: type: object properties: name: type: string description: The name of the invalid parameter. reason: type: string description: The reason why the parameter is invalid. '401': description: Unauthorized content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id009 properties: *id010 '403': description: Forbidden content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id009 properties: *id010 '404': description: Not Found content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id009 properties: *id010 /v1/webhooks/{id}/trigger: post: tags: - Webhooks summary: Trigger a webhook by id description: Trigger a webhook manually, without needing to perform the action that would normally trigger the webhook. operationId: triggerWebhookById parameters: - name: id in: path required: true schema: description: The unique identifier of a webhook. type: string pattern: ^[a-zA-Z0-9]+$ example: wh123abc45 security: - basic_auth: [] requestBody: description: Payload to be sent when making the webhook request. content: application/json: schema: type: object properties: learnerId: allOf: - description: "The unique identifier of a learner. \n\nRequired when the webhook type is `LEARNER_TRAINING_CAMPAIGN_COMPLETED`." type: string pattern: ^[a-zA-Z0-9]+$ example: abc123def4 trainingCampaignId: allOf: - description: "The unique identifier of a training campaign. \n\nRequired when the webhook type is `LEARNER_TRAINING_CAMPAIGN_COMPLETED`." type: string pattern: ^[a-zA-Z0-9]+$ example: tc456xyz78 responses: '204': description: No Content '400': description: Bad Request content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: &id011 - title properties: &id012 title: description: A short, human-readable summary of the problem type. type: string detail: description: A human-readable explanation specific to this occurrence of the problem. type: string invalid-params: description: An array of objects, each representing a parameter that was invalid. type: array items: type: object properties: name: type: string description: The name of the invalid parameter. reason: type: string description: The reason why the parameter is invalid. '401': description: Unauthorized content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id011 properties: *id012 '403': description: Forbidden content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id011 properties: *id012 '404': description: Not Found content: application/json: schema: type: object additionalProperties: true minProperties: 1 description: JSON description of the issues based on the The Problem Details JSON Object [[RFC7807](https://tools.ietf.org/html/rfc7807)]. required: *id011 properties: *id012 components: securitySchemes: basic_auth: description: Send requests with the Authorization header that contains the word `Basic` followed by a space and a base64-encoded string of the username and api key, `username:apiKey`. type: http scheme: basic x-tagGroups: - name: General tags: - Learners - Training Campaigns - Learner Training Campaigns - Learner Training Modules - Webhooks