Integrating with a Custom Webhook

How It Works

Example of a billing meter with a Webhook destination

With a Billing Meter that uses Webhooks, Moesif will automatically meter the usage send the usage data to your Webhook endpoint. Moesif Billing Meters support a variety of billing models including prepaid, postpaid, Pay As You Go (PAYG) and more. If you have different features or metrics you need to charge on, you can create multiple meters in Moesif, each linked to a plan.

Creating a Billing Meter that sends usage data to custom webhooks adds unlimited possibilities. Using custom Webhooks makes it easy for you to integrate a Moesif Billing Meter with a custom or in-house billing platform. Moesif will handle the scheduling and reporting of usage, you just need to implement a custom webhook handler to add the reported usage to the respective customer’s invoice/subscription in your internal billing system.

This page assumes that you already have a Webhook service/endpoint already created and available so that Moesif will be able to send messages/requests to it.

Configuring Your Webhook in Moesif

With your Webhook URL handy, go to the Billing Meters page in Moesif by clicking the Billing Meters link in the left-side menu. From the Billing Meters main screen, click on the Add Billing Meter button in the top right. This will display the Create New Billing Meter screen.

1 - Select Webhook Billing Provider

Click on the Select billing provider dropdown (under the Billing Provider section) and select Custom (Via Webhook). Once selected, you will see the Webhook(s) and Plan dropdowns become available.

2 - Select Your Webhook(s)

To select the Webhook to send usage to, click on the Select Webhook(s) dropdown. If you have a Webhook already available/added in Moesif, you can select it from the list. Multiple Webhooks can be selected for a single meter. If not, select the Add New Webhook option to add a new webhook. In the Create Notification Channel modal that appears, you’ll need to add:

  • Channel Name
    • This will be the name that your webhook is referred to as in Moesif.
  • Channel Type
    • This will be defaulted to Webhook.
  • Webhook URL
    • This is your Webhook URL that you want Moesif to send requests to.
  • Method
    • This is the HTTP method, POST or PUT that should be used when sending requests to your Webhook URL.
  • Request Headers
    • These are any headers that you want to add to the Webhook request, such as an Authorization or Content-Type header. To authenticate requests as coming from Moesif, we recommend adding a secret key in a request header.

Once the Webhook fields are filled out, click Save.

3 - Select/Create a Billing Plan

To select the plan that usage should be attributed to, click on the Select Plan dropdown. IF you have plans that are already created, you can select them here. If not, select the Add New Plan option to add a new plan. In the Create Billing Plan modal that appears, you’ll need to add:

  • Plan Name
    • This is the name for your plan that will be displayed in Moesif.
  • External Plan Id
    • This can be used to store the Plan Id from your billing solution or any unique identifier that will help with mapping usage.
  • Reporting Schedule
  • Reporting Period

Once the Plan fields are filled out in the modal, click Create.

4 - Set the “Report for Subscriptions in” Option

In the Report for Subscriptions in selector, you will select what subscription status you want to meter. For instance, you may want to meter usage only for subscriptions which have an Active status. Options here include:

  • Active
  • Future
  • In Trial
  • Paused
  • Non-Renewing

5 - Configure the Filters and Metrics and Save the Billing Meter

These details are covered in details on our Adding Billing Criteria docs page. Once the billing criteria is set, click the Create button in the top-right of the screen.

Editing and Updating a Webhook

To edit a Webhook, click on the Settings menu in the bottom left of the screen (shown as your name) and select Notification Channels. On the Notification Channels screen, select your Webhook by clicking on its name. On the modal that appears you can update and edit the Webhook settings. Once completed, click Save.

Editing and Updating a Plan

To edit a Plan, click on the Settings menu in the bottom left of the screen (shown as your name) and select Billing Plans. On the Billing Plans screen, select your Plan by clicking on its name. On the modal that appears you can update and edit the Plan’s settings. Once completed, click Save.

For auditing purposes, the only detail that can be changed for a plan is the plan’s Name. To edit it further, you’ll need to archive the existing plan and create a new one.

Choosing a Reporting Schedule and Reporting Period

Currently there are three options for Reporting Schedule in the Moesif Billing Plan configuration. These options include:

  • Continuous Reporting
    • This option reports usage in near real-time throughout the billing period. This is the recommended option if your billing system can handle aggregating multiple reports in same billing period.
  • Calendar-Aligned Billing
    • This option reports all usages on same calendar date or quarter, such as the last day of the month.
  • Subscription-Based Billing
    • This option reports the usage separately for each subscription based on a subscription end date. You will need to keep these up to date using the Moesif Update Companies API.

For each of these Reporting Schedule options, there are also configurable Reporting Periods. For Continuous Reporting the Reporting Period select will aggregate usage within the chosen time period before sending to the Webhook. For Continuous Reporting, these Reporting Periods include:

  • Every 5 Minutes
  • Every 15 Minutes
  • Every Hour

For Calendar-Aligned Billing the Reporting Period select will aggregate usage within the chosen calendar period before sending to the Webhook. For Calendar-Aligned Billing, these Reporting Periods include:

  • Daily
  • Weekly
  • Monthly
  • Quarterly

For Subscription-Based Billing the Reporting Period is based on the subscription.current_period_start and subscription.current_period_end set in the Company object. For subscription-based billing to work, your custom solution will need to write the subscription.current_period_start and subscription.current_period_end (or equivalent) to Moesif. This can be done by using the Moesif API.

Updated: