Endpoints

Endpoints allow you to run workflows when external systems make HTTP requests to MonetizationOS, enabling two-way integration between your applications and the platform.

Endpoints enable you to proactively drive functionality in MonetizationOS from external systems or retrieve information from MonetizationOS for use elsewhere. Each endpoint executes a workflow that you define to handle the incoming request.

Common use cases include receiving webhooks from payment systems to update user records, creating APIs for your frontend applications to record user interactions, or building custom integrations with third-party services.

To begin, navigate to the Endpoints section in the left-hand navigation menu.

Your endpoints page shows a list of configured endpoints and allows you to edit and delete existing endpoints, or add new ones.

Create an Endpoint

To add an endpoint, click 'Add an Endpoint'.

You will be prompted to configure your endpoint with the following details:

• Name: Give your endpoint a descriptive name
• Description: Optional description of the endpoint's purpose
• Path: The URL path for your endpoint (must start with a slash, e.g., /webhook/stripe)
• Method: HTTP method (GET, POST, PUT, DELETE, PATCH)
• Access Level: Choose the access level for your endpoint:
  • Secret Key: Requires authentication with your secret key via the X-MOS-Key header
  • Public Key: Accepts authentication with your public key via the X-MOS-Key header
  • No Key: No authentication required

Please note: When using an open and public endpoint, anyone with the URL can trigger the endpoint without restrictions. Ensure you verify identity in your workflow before trusting requests.

If you have Brands enabled, you must link this endpoint to a particular brand or brands by clicking the 'Link Brands' button. This means the endpoint will only be available in environments linked to that specific brand or brands.

Note that path and method combinations must be unique within a brand - overlapping endpoints are not allowed.

Once configured, click 'Create Endpoint'. You will then be taken to the endpoint management area with two tabs: Workflow and Manage.

Workflow

The Workflow tab is broken into two sections: Endpoint Settings and Workflow.

Endpoint Settings

The Endpoint Settings section allows you to:

• View and copy the endpoint URL
• Filter between Preview and Live environment URLs
• Update the path, method, and access level

Workflow

The Workflow section allows you to write the code that will execute when your endpoint is called. Your workflow receives the request data and can process it as needed.

You can preview, enable or disable the workflow, or click 'Edit' to update it.

The workflow has access to:

• Request object: Including body (as text), headers, parameters, and method
• Environment: Environment context and configuration
• Utilities: All existing workflow utilities for interacting with MonetizationOS, including identity operations

Example

Here's an example of a hello world webhook endpoint:

const workflow: EndpointWorkflow = async ({ request, env, utils }) => {
  return new Response("hello world");
};

export default workflow;

Manage

The Manage tab allows you to edit the endpoint name, description, and linked brands.

You can also delete your endpoint from this tab.

Request Handling

Endpoints can handle any text-based request body structure up to 5MB in size. Requests exceeding this limit will be rejected with a 413 status code.

Your endpoint workflows should return a Response object to send data back to the calling system.

Endpoint URLs

Your endpoints will be accessible at URLs following this pattern:

https://api.monetization.dev/api/v1/envs/<environmentId>/endpoints/<path>

You can find your environmentId on the environments page.

Monitoring

Endpoint executions are tracked in the observability interface, showing request details, execution status, and any errors that occur during processing.

Editing an Endpoint

To edit an endpoint, locate it in your endpoint list, then click the 'Edit' icon in the actions column.

This will bring up the same screen you used to configure your endpoint. Make any relevant changes to the workflow logic or configuration, and click 'Update'.

Deleting an Endpoint

To delete an endpoint, locate it in your endpoint list, then click the 'Delete' icon in the actions column.

You will be prompted to confirm you wish to remove the endpoint. This action cannot be undone.

To continue, click 'Delete'. Otherwise, click 'Cancel'.