Integrating with RoSaaS Webhooks

RoSaaS provides a powerful and flexible webhook system that allows external systems to receive real-time notifications about various events. This guide will walk you through the steps necessary to integrate your system with RoSaaS webhooks, ensuring seamless communication and event handling.

Receive RoSaaS Events in Your Webhook Endpoint

Listen to events in your RoSaaS account on your webhook endpoint so your integration can automatically trigger reactions.

Why Use Webhooks

When building RoSaaS integrations, you might want your applications to receive events as they occur in your RoSaaS accounts, so that your backend systems can execute actions accordingly.

To enable webhook events, you need to register webhook endpoints. After you register them, RoSaaS can push real-time event data to your application’s webhook endpoint when events happen in your RoSaaS account. RoSaaS uses HTTPS to send webhook events to your app as a JSON payload that includes an Event object.

Receiving webhook events is particularly useful for listening to asynchronous events such as when a tenant’s status changes, a subscription is upgraded, or a payment fails.

Event Overview

RoSaaS uses events to notify you of important changes and activities in your account. When a significant event occurs, such as a tenant’s status changing from active to passive, RoSaaS creates a new Event object. This object contains details about the event and its context.

Events are triggered by changes in the state of various resources within RoSaaS. For example, a Tenant.StatusChanged event occurs when a tenant’s status changes. The data field of the event contains the state of the resource at the time of the change. In the case of a Tenant.StatusChanged event, it might include information about the previous status (e.g., active) and the new status (e.g., passive) of the tenant.

You can retrieve individual events or lists of events from RoSaaS using API endpoints. Additionally, RoSaaS provides a webhooks system that allows you to receive Event objects directly to an endpoint on your server. This enables your integration to automatically react to events, such as updating your internal systems when a Tenant.StatusChanged event occurs.

Event Type Overview

ChatGPT markdown Copy code

  • Tenant.RegisteredInRoSaasDb

    Indicates that a tenant has been registered in the RoSaaS database.

  • Tenant.StatusChanged

    Indicates a change in the status of a tenant.

  • Subscription.Trial.UpgradedToStandard

    Indicates that a trial subscription has been upgraded to a standard subscription.

  • Subscription.Upgrade.Enabled

    Indicates that users have requested an upgrade to an advanced plan.

  • Subscription.Upgrade.UpgradingDisabled

    Indicates that the request for an upgrade has been canceled or disabled.

  • Subscription.Upgrade.HasBeenUpgraded

    Indicates that a subscription has been successfully upgraded.

  • Subscription.Downgrade.DowngradeEnabled

    Indicates that users have requested a downgrade to a lower-tier plan.

  • Subscription.AutoRenewal.Enabled

    Indicates that auto-renewal for a subscription is enabled.

  • Subscription.Downgrade.DowngradingDisabled

    Indicates that the request for a downgrade has been canceled or disabled.

  • Subscription.Downgrade.ForcedDowngradeEnabled

    Indicates that a forced downgrade has been enabled.

  • Subscription.AutoRenewal.Disabled

    Indicates that auto-renewal for a subscription is disabled.

  • Subscription.AutoRenewal.HasBeenRenewedAutomatically

    Indicates that a subscription has been automatically renewed.

  • Subscription.Downgrade.HasBeenDowngraded

    Indicates that a subscription has been successfully downgraded.

  • ExternalSystem.CreatedTenantResources

    Indicates that tenant resources have been created in an external system.

  • Tenant.Availability.ChangedToUnhealthy

    Indicates a change in the availability status of a tenant to unhealthy.

  • Subscription.SuspendedDueToUnpaid

    Indicates that a subscription has been suspended due to unpaid charges.

  • Subscription.AutoRenewal.AutoRenewalDisabled

    Indicates that auto-renewal for a subscription is disabled.

  • Tenant.Availability.ChangedToHealthy

    Indicates a change in the availability status of a tenant to healthy.

Event Object

The Event object we send to your webhook endpoint provides a snapshot of the object that changed. They might include a previous_attributes property that indicates the change, when applicable.

See the full list of event types that we send to your webhook.

Example Event Payload

The following event shows a subscription update at the end of a trial.

{
  "TenantSystemName": "example_tenant", // Tenant system name
  "EventCode": 1, // Unique event code
  "Event": "TrialSubscriptionUpgradedToStandard", // Event type
  "MetaData": {
    // Event-specific data
    "subscription_id": "sub_123456789", // Subscription ID
    "status": "upgraded" // New status
  },
  "Created": "2024-05-28T12:34:56Z" // UTC timestamp
}

Create an Endpoint in Your System

  • To integrate your external system with RoSaaS webhooks, follow these steps:
  1. Create an Endpoint in Your System:

  • Implement an endpoint in your system similar to the “Notify me” endpoint provided by RoSaaS. This endpoint should:

    • Accept incoming webhook notifications.
    • Include a Signing Secret in the header for secure verification.
    • Always return the following data:
      • TenantSystemName (string): The name of the tenant associated with your product within the RoSaaS system.
      • Event (string): The type of event being notified.
      • EventCode (int): A unique code representing the event type.
      • MetaData (dynamic): Additional dynamic metadata related to the event.
      • Created (DateTime): The timestamp indicating when the event notification was received.

  1. Access RoSaaS Panel:

    • Log in to the RoSaaS panel using your credentials.

  2. Navigate to Products Page:

    • Once logged in, navigate to the “Products” page either from the products list or using the sidebar navigation.

  3. Select Product and Navigate to Webhook Tab:

    • Choose the desired product from the products list or sidebar.
    • In the product details page, locate and select the “Webhook” tab.

  4. Add Endpoint:

    • In the top section of the “Webhook” tab, you will find an “Add Endpoint” button. Click on it to proceed.

  5. Fill Endpoint Form:

    • A dialog form will appear for adding a new endpoint. Fill out the following details:
      • Endpoint URL: Provide the URL of the endpoint you created in your system.
      • Signing Secret: Either press the “Generate” button to generate a random secret or provide a specific value. This signing secret will be used in the header of the webhook notification requests for secure verification.
      • Select Events to Listen To: Choose one or more events from the list or select “Select All” to listen to all events.
      • Description: Optionally, provide a description for the webhook endpoint.

  6. Submit Form:

    • After filling out the form, submit it to add the webhook endpoint to your RoSaaS product.

  7. Receive Webhook Notifications:

    • Expose an HTTP endpoint in your system to receive webhook notifications. In the example above, the endpoint is /api/WebhookListener/notifyme.
    • The endpoint should accept POST requests containing the webhook payload data in the request body.
    using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;
using System.Threading.Tasks;
using Microsoft.Extensions.Configuration;
using Microsoft.AspNetCore.Http;
namespace YourNamespace.Controllers
{
[Route("api/[controller]")]
[ApiController]
public class WebhookListenerController : ControllerBase
{
private readonly IConfiguration \_configuration;

      public WebhookListenerController(IConfiguration configuration)
      {
            _configuration = configuration;
      }

      // POST: api/<WebhookListenerController>/notifyme
      [HttpPost("notifyme")]
      public async Task<IActionResult> NotifymeAsync(GlobalPayloadRequest model, [FromHeader(Name = "X-Signing-Secret")] string signingSecret)
      {
            // Retrieve the expected signing secret from configuration
            var expectedSecret = _configuration["RoSaaS:SigningSecret"];

            // Validate the signing secret
            if (signingSecret != expectedSecret)
            {
               return Unauthorized("Invalid signing secret.");
            }

            // Store the received webhook payload data in your system
            // Example: Store.DB.Add(model);
            // Your implementation here

            return Ok();
      }
   }
}

Secure Your Webhook Endpoint

Ensure that your webhook endpoint is secure by validating the signature of incoming requests.

By following these steps, your external system will be successfully integrated with RoSaaS webhooks, allowing seamless communication and event notifications between systems.

← RoSaaS API Integration
Tenant Registered In RoSaas Db →