Platform Webhooks Guide for Partners

Appxite Updated by Appxite

Introduction

This article provides comprehensive guidance for Sellers on configuring and using webhooks within the Platform. Webhooks enable external systems to receive real-time notifications about key platform events, including Order updates, provisioning results, and Subscription changes. It emphasizes the importance of proper webhook configuration and notes that webhooks can be configured at both distributor and Seller levels. In the Notification Settings section, (Seller Admin) can configure webhooks for various platform events.

In this article:

In the Notification Settings section, you (Seller Admin) can configure webhooks to receive real-time notifications.

NOTE! Webhook settings for Sellers do not override distributor settings. Each webhook is sent independently.

Overview

Webhooks allow external systems to receive real-time notifications about key events on the Platform, such as Order updates, provisioning results, and Subscription changes.

Webhooks can be configured at both distributor and Seller levels. These configurations are independent and cumulative, meaning if both are set, the Platform sends a separate webhook to each endpoint.

To streamline webhook management, configuration options are conveniently located in the Settings → Notification Settings → Events section. Switching between different webhook events can be done seamlessly within the interface.

To check the Postman documentation with all bodies and fields descriptions see Webhook Documentation

Webhook Configuration

To configure a webhook:

  1. Go to the Settings section
  2. Choose Notification Settings
  3. Click Events tab
  4. Select the notification event for which you would like to configure the webhook and click Edit
  5. Choose Webhook tab
  6. Specify the following required fields:
Field Description Required
URL Endpoint that will receive the webhook payload Yes
Authorization Header Optional value used for authentication No
Content Type Payload format; choose from the supported types below Yes
  1. Click Save

Supported Content Types

The Platform supports the following content types for webhook payloads:

  • application/json
  • application/x-www-form-urlencoded

Common Webhook Fields

All webhooks share a common structure with the following fields:

Field Type Description
Subject string/null Always null for webhooks
TemplateName string Identifies the webhook event type
TemplateData object Contains the main event data with key-value pairs
TemplateLoopData object Contains arrays of related Order items
TemplateNestedLoopData object Contains arrays of related prices for Order items
AuditId string (GUID) Unique identifier for tracking the webhook event

Common TemplateData Fields

All webhook payloads include these standard TemplateData fields:

Field Type Description
BaseColor string (hex) Brand color for UI elements
ButtonFontColor string (hex) Font color for buttons
DomainMainLogoUrl string (URL) URL to the organization's logo
HostOrganizationAdminEmail string (email) Administrator email address
ResellerName string Name of the Seller organization
PortalName string Name of the portal
PortalUrl string (URL) URL to the portal
DistributorLogoUrl string (URL) URL to distributor's logo (when applicable)
DistributorId string (GUID) Unique identifier for the distributor (when applicable)
ResellerId string (GUID) Unique identifier for the Seller
ResellerErpId string ERP system identifier for the Seller (when applicable)
CustomerId string (GUID) Unique identifier for the Customer
OrderId string (GUID) Unique identifier for the Order (when applicable)

Webhook Payloads

Below are detailed payload examples for the most commonly used webhook notifications. These examples use mock data for demonstration purposes.

Subscriptions - Order Placed

TemplateName: OnPurchaseNotification

This webhook is used for notifying Customers about submitting new Offer purchases and Subscription change orders.

Example Payload

{
  "Subject": null,
  "TemplateName": "OnPurchaseNotification",
  "TemplateData": {
    "BaseColor": "#4CAF50",
    "ButtonFontColor": "#000000",
    "DomainMainLogoUrl": "https://example.com/logo.png",
    "HostOrganizationAdminEmail": "admin@example.com",
    "ResellerName": "Example Reseller",
    "PortalName": "Example Portal",
    "PortalUrl": "https://portal.example.com",
    "DistributorLogoUrl": "https://example.com/distributor-logo.png",
    "OrderId": "12345678-1234-1234-1234-123456789012",
    "OrderNumber": "12345",
    "OrganizationShortName": "Example Org",
    "OrganizationFullName": "Example Organization Inc.",
    "ResellerId": "23456789-2345-2345-2345-234567890123",
    "CustomerId": "34567890-3456-3456-3456-345678901234",
    "CustomerFullName": "Example Customer",
    "CustomerShortName": "Example Cust",
    "CurrencyCode": "EUR",
    "ShowPreferredCurrencyMessage": "FALSE"
  },
  "TemplateLoopData": {
    "OrderItems": {
      "OrderItemTitle": ["Example Product"],
      "Quantity": ["5"],
      "Prices": ["45678901-4567-4567-4567-456789012345"]
    }
  },
  "TemplateNestedLoopData": {
    "45678901-4567-4567-4567-456789012345": {
      "Item": ["45.22 every 1 month"]
    }
  },
  "AuditId": "56789012-5678-5678-5678-567890123456"
}

Specific TemplateData Fields

Field Type Description
OrderNumber string Sequential Order number
OrganizationShortName string Short name of the organization
OrganizationFullName string Full name of the organization
CustomerFullName string Full name of the Customer
CustomerShortName string Short name of the Customer
CurrencyCode string ISO currency code (e.g., EUR, USD)
ShowPreferredCurrencyMessage string Flag to show preferred currency message

TemplateLoopData Fields

Field Type Description
OrderItems object Contains arrays of order item information
OrderItemTitle array Array of product titles in the Order
Quantity array Array of quantities for each product
Prices array Array of price reference IDs for nested data

TemplateNestedLoopData Fields

The TemplateNestedLoopData contains pricing information referenced by IDs from the TemplateLoopData.OrderItems.Prices array. Each price ID corresponds to an object containing:

Field Type Description
Item array Array of pricing details (e.g., "45.22 every 1 month")

Order - Status Change

TemplateName: OrderStatusChanged

This webhook is triggered when the status of the Order changed. It applies for new offer orders or subscription change orders.

Possible Order Statuses

• 0 - Draft - is the status of a Quote. It has not yet been sent to the Customer but is in draft mode for the Seller creating it.

• 1 - Prepared - indicates the order has been prepared and is ready for processing.

• 2 - Deleted - The Order has been deleted.

• 3 - Rejected - The Order has been rejected and will not be processed.

• 4 - In Progress - The provisioning has been started but not yet finished (not available for Microsoft Offers).

• 5 - Waiting Proposal Approval - The order is awaiting approval from the proposal stage.

• 6 - Waiting Order Approval - The order is awaiting final approval before provisioning.

• 7 - Waiting Provisioning Approval - The order is awaiting approval to begin provisioning.

• 8 - Completed Success - The Order has been completed and the Subscription has been purchased successfully.

• 9 - Completed Error - The Order has been completed and sent to the Vendor, but the Vendor returns an error message: fields are not filled in, email address is invalid for the Customer, etc.

• 10 - Canceled Success - The Order has been successfully canceled.

• 11 - Action Required - The Order requires manual intervention or additional action from the user or administrator.

Note: The numeric status IDs (0-11) above are used in the API responses and should be referenced when integrating with the platform programmatically. The OrderStatusId field in webhook payloads will contain these numeric values.

Example Payload

{
  "Subject": null,
  "TemplateName": "OrderStatusChanged",
  "TemplateData": {
    "BaseColor": "#ff0000",
    "ButtonFontColor": "#ffffff",
    "DomainMainLogoUrl": "https://example.com/logo.png",
    "HostOrganizationAdminEmail": "admin@example.com",
    "ResellerName": "Example Reseller",
    "PortalName": "Example Portal",
    "PortalUrl": "https://portal.example.com",
    "DistributorLogoUrl": "https://example.com/distributor-logo.png",
    "OrderId": "12345678-1234-1234-1234-123456789012",
    "OrderNumber": "12345",
    "OrderSequenceNumber": "1001",
    "OrderStatusId": "4",
    "OrderStatusName": "In progress",
    "ResellerId": "23456789-2345-2345-2345-234567890123",
    "ResellerShortName": "Example Reseller",
    "ResellerFullName": "Example Reseller Inc.",
    "CustomerId": "34567890-3456-3456-3456-345678901234",
    "CustomerShortName": "Example Cust",
    "CustomerFullName": "Example Customer",
    "CurrencyCode": "EUR",
    "ShowPreferredCurrencyMessage": "FALSE"
  },
  "TemplateLoopData": {
    "OrderItems": {
      "OrderItemTitle": ["Example Product"],
      "Quantity": ["300"],
      "Prices": ["45678901-4567-4567-4567-456789012345"]
    }
  },
  "TemplateNestedLoopData": {
    "45678901-4567-4567-4567-456789012345": {
      "Item": ["24192.00 every 12 months"]
    }
  },
  "AuditId": "56789012-5678-5678-5678-567890123456"
}

Specific TemplateData Fields

Field Type Description
OrderNumber string Sequential Order number
OrderSequenceNumber string Sequence number of the Order
OrderStatusId string Numeric identifier for the Order status
OrderStatusName string Name of the Order status
ResellerShortName string Short name of the Seller
ResellerFullName string Full name of the Seller
CustomerShortName string Short name of the Customer
CustomerFullName string Full name of the Customer
CurrencyCode string ISO currency code (e.g., EUR, USD)
ShowPreferredCurrencyMessage string Flag to show preferred currency message

TemplateLoopData Fields

Field Type Description
OrderItems object Contains arrays of order item information
OrderItemTitle array Array of product titles in the Order
Quantity array Array of quantities for each product
Prices array Array of price reference IDs for nested data

TemplateNestedLoopData Fields

The TemplateNestedLoopData contains pricing information referenced by IDs from the TemplateLoopData.OrderItems.Prices array. Each price ID corresponds to an object containing:

Field Type Description
Item array Array of pricing details (e.g., "24192.00 every 12 months")

Subscriptions - Provisioning Successful

TemplateName: OfferProvisioned

Notification about success result during new Offer provision.

Example Payload

{
  "Subject": null,
  "TemplateName": "OfferProvisioned",
  "TemplateData": {
    "BaseColor": "#4CAF50",
    "ButtonFontColor": "#000000",
    "DomainMainLogoUrl": "https://example.com/logo.png",
    "HostOrganizationAdminEmail": "admin@example.com",
    "ResellerName": "Example Reseller",
    "PortalName": "Example Portal",
    "PortalUrl": "https://portal.example.com",
    "DistributorId": "12345678-1234-1234-1234-123456789012",
    "ResellerId": "23456789-2345-2345-2345-234567890123",
    "ResellerErpId": "ERP-12345",
    "CustomerId": "34567890-3456-3456-3456-345678901234",
    "CustomerName": "Example Customer",
    "OfferName": "Example Offer",
    "OrderId": "45678901-4567-4567-4567-456789012345",
    "OrderDate": "2025.07.22",
    "OrderItemId": "56789012-5678-5678-5678-567890123456",
    "SubscriptionId": "67890123-6789-6789-6789-678901234567",
    "SubscriptionName": "Example Subscription"
  },
  "TemplateLoopData": {},
  "TemplateNestedLoopData": {},
  "AuditId": "78901234-7890-7890-7890-789012345678"
}

Specific TemplateData Fields

Field Type Description
CustomerName string Full name of the Customer
OfferName string Name of the Offer
OrderDate string (date) Date when the Order was placed
OrderItemId string (GUID) Unique identifier for the Order item
SubscriptionId string (GUID) Unique identifier for the Subscription
SubscriptionName string Name of the Subscription
NOTE! For this webhook event, TemplateLoopData and TemplateNestedLoopData are empty objects as all relevant data is contained in TemplateData.

Subscriptions - Provisioning Failed

TemplateName: OfferProvisionError

Notification about error(s) which occurred during new Offer provision.

Example Payload

{
  "Subject": null,
  "TemplateName": "OfferProvisionError",
  "TemplateData": {
    "BaseColor": "#ff0000",
    "ButtonFontColor": "#ffffff",
    "DomainMainLogoUrl": "https://example.com/logo.png",
    "HostOrganizationAdminEmail": "admin@example.com",
    "ResellerName": "Example Reseller",
    "PortalName": "Example Portal",
    "PortalUrl": "https://portal.example.com",
    "DistributorLogoUrl": "https://example.com/distributor-logo.png",
    "ResellerId": "12345678-1234-1234-1234-123456789012",
    "CustomerId": "23456789-2345-2345-2345-234567890123",
    "CustomerName": "Example Customer",
    "OfferName": "Example Offer",
    "OrderId": "34567890-3456-3456-3456-345678901234",
    "OrderDate": "2025.09.05",
    "OrderNumber": "12345",
    "ErrorMessage": "Example error message describing the provisioning issue",
    "SubscriptionId": "45678901-4567-4567-4567-456789012345",
    "SubscriptionName": "Example Subscription"
  },
  "TemplateLoopData": {},
  "TemplateNestedLoopData": {},
  "AuditId": "56789012-5678-5678-5678-567890123456"
}

Specific TemplateData Fields

Field Type Description
CustomerName string Full name of the Customer
OfferName string Name of the Offer
OrderDate string (date) Date when the Order was placed
OrderNumber string Sequential Order number
ErrorMessage string Error message describing the provisioning issue
SubscriptionId string (GUID) Unique identifier for the Subscription
SubscriptionName string Name of the Subscription
NOTE! For this webhook event, TemplateLoopData and TemplateNestedLoopData are empty objects as all relevant data is contained in TemplateData.

Subscriptions - Changes Successful

TemplateName: SubscriptionChangeSuccess

Notification about success(s) which occurred during any Subscription modification attempts. This webhook is triggered for the following types of changes:

  • Subscription status updates
  • Plan modifications
  • Billing changes
  • Configuration adjustments

Example Payload

{
  "Subject": null,
  "TemplateName": "SubscriptionChangeSuccess",
  "TemplateData": {
    "BaseColor": "#E12426",
    "ButtonFontColor": "#ffffff",
    "DomainMainLogoUrl": "https://example.com/logo.png",
    "HostOrganizationAdminEmail": "admin@example.com",
    "ResellerName": "Example Reseller",
    "PortalName": "Example Portal",
    "PortalUrl": "https://portal.example.com",
    "DistributorId": "12345678-1234-1234-1234-123456789012",
    "ResellerId": "23456789-2345-2345-2345-234567890123",
    "ResellerErpId": "ERP-12345",
    "CustomerId": "34567890-3456-3456-3456-345678901234",
    "CustomerName": "Example Customer",
    "SubscriptionId": "45678901-4567-4567-4567-456789012345",
    "SubscriptionName": "Example Subscription",
    "OrderId": "56789012-5678-5678-5678-567890123456",
    "OrderDate": "2025.06.27",
    "OrderItemId": "67890123-6789-6789-6789-678901234567",
    "PreviousSubscriptionName": "Example Subscription - Old",
    "PreviousQuantity": "1",
    "PreviousStatus": "Active",
    "PreviousBillingFrequency": "Every 3 months",
    "PreviousAutoRenewEnabled": "ON",
    "CurrentSubscriptionName": "Example Subscription - New",
    "CurrentQuantity": "17",
    "CurrentStatus": "Active",
    "CurrentBillingFrequency": "Every 12 months",
    "CurrentAutoRenewEnabled": "OFF"
  },
  "TemplateLoopData": {},
  "TemplateNestedLoopData": {},
  "AuditId": "78901234-7890-7890-7890-789012345678"
}

Specific TemplateData Fields

Field Type Description
CustomerName string Full name of the Customer
SubscriptionId string (GUID) Unique identifier for the Subscription
SubscriptionName string Name of the Subscription
OrderDate string (date) Date when the Order was placed
OrderItemId string (GUID) Unique identifier for the Order item
PreviousSubscriptionName string Previous name of the Subscription
PreviousQuantity string Previous quantity
PreviousStatus string Previous status of the Subscription
PreviousBillingFrequency string Previous billing frequency
PreviousAutoRenewEnabled string Previous auto-renewal status
CurrentSubscriptionName string Current name of the Subscription
CurrentQuantity string Current quantity
CurrentStatus string Current status of the Subscription
CurrentBillingFrequency string Current billing frequency
CurrentAutoRenewEnabled string Current auto-renewal status
NOTE! For this webhook event, TemplateLoopData and TemplateNestedLoopData are empty objects as all relevant data is contained in TemplateData.

Product Catalog - Catalog Changed

TemplateName: ProductCatalogChanged

This webhook is triggered when changes are made to the Product catalog structure, including when Product categories or Products are added or deleted from a catalog.

Example Payload

{
  "Subject": null,
  "TemplateName": "ProductCatalogChanged",
  "TemplateData": {
    "BaseColor": "#E12426",
    "ButtonFontColor": "#ffffff",
    "DomainMainLogoUrl": "https://example.com/logo.svg",
    "HostOrganizationAdminEmail": "admin@example.com",
    "ResellerName": "Example Reseller",
    "PortalName": "Example Portal",
    "PortalUrl": "example.rethinkportal.com",
    "DistributorLogoUrl": "",
    "ProductCatalogId": "b6d6221a-c301-4e86-8801-c510f6e46a2d",
    "CustomerCategoryId": "",
    "CustomerCategoryName": null,
    "TimestampUtc": "12/3/2025 9:26:54 AM"
  },
  "TemplateLoopData": {
    "ProductCategoriesAdded": {
      "Id": ["dec90b38-d41f-43a3-9556-f0134f3bfcd8"],
      "UrlName": ["Impostor"]
    },
    "ProductsAdded": {
      "ProductCategoryId": [
        "dec90b38-d41f-43a3-9556-f0134f3bfcd8",
        "dec90b38-d41f-43a3-9556-f0134f3bfcd8"
      ],
      "ProductCategoryUrlName": ["Impostor", "Impostor"],
      "ProductId": [
        "2318bc2c-c3ed-4228-89a7-cea4e90b3635",
        "39ff4885-aa54-4555-b50d-4a9b352fc5df"
      ],
      "ProductName": ["80427 Testing", "Example Offer"],
      "ProductExternalId": [
        "2318bc2c-c3ed-4228-89a7-cea4e90b3635",
        "39ff4885-aa54-4555-b50d-4a9b352fc5df"
      ],
      "Offers": [
        "3566d87d-f25c-4cba-851b-d89135f4e369",
        "a5421bbf-448d-43e3-8b73-1012e33e2703"
      ]
    }
  },
  "AuditId": "e4f3252f-6d93-4973-a7ff-daaaba19d923"
}

Specific TemplateData Fields

Field Type Description
ProductCatalogId string (GUID) Unique identifier for the Product catalog
CustomerCategoryId string (GUID) Unique identifier for the Customer Segment (if applicable)
CustomerCategoryName string/null Name of the Customer Segment (if applicable)
TimestampUtc string (datetime) UTC timestamp when the catalog change occurred

Product Catalog - Product Offers Changed

TemplateName: ProductCatalogProductOffersChanged

This webhook is triggered when the visibility status of Offers within a specific Product is changed, including when Offers become viewable or hidden in the catalog.

Example Payload

{
  "Subject": null,
  "TemplateName": "ProductCatalogProductOffersChanged",
  "TemplateData": {
    "BaseColor": "#4CAF50",
    "ButtonFontColor": "#000000",
    "DomainMainLogoUrl": "https://example.com/logo.svg",
    "HostOrganizationAdminEmail": "admin@example.com",
    "ResellerName": "Demo Distributor",
    "PortalName": "Demo Distributor",
    "PortalUrl": "demo-disti.example.net",
    "DistributorLogoUrl": "",
    "ProductCatalogId": "f02defed-7c6c-47d7-9747-164c0b2c7706",
    "CustomerCategoryId": "",
    "CustomerCategoryName": null,
    "ProductCategoryId": "9faeeae6-c908-4497-a29a-a173ba8c4336",
    "ProductCategoryUrlName": "Featured",
    "ProductId": "b94cfa0d-8833-48fa-8f73-73d2a4ae7bae",
    "ProductName": "Banana",
    "ProductExternalId": "b94cfa0d-8833-48fa-8f73-73d2a4ae7bae",
    "TimestampUtc": "12/3/2025 9:25:51 AM"
  },
  "TemplateLoopData": {
    "OffersViewable": {
      "OfferId": [
        "b53bba9c-77ef-4af1-9417-957a5a20e55f",
        "f5f91fe0-5ddf-4527-9afe-aae2dba7ad0f"
      ],
      "OfferName": ["Banana Round round", "Example Offer"],
      "OfferExternalId": [
        "b53bba9c-77ef-4af1-9417-957a5a20e55f",
        "f5f91fe0-5ddf-4527-9afe-aae2dba7ad0f"
      ],
      "OfferStatus": ["Active", "Active"]
    },
    "OffersHidden": {
      "OfferId": ["14b87964-0550-440e-bdbf-0237181cdd28"],
      "OfferName": ["Banana to try"],
      "OfferExternalId": ["14b87964-0550-440e-bdbf-0237181cdd28"],
      "OfferStatus": ["Invalid"]
    }
  },
  "AuditId": "46b99ffd-c899-485f-8f29-71d2d56af374"
}

Specific TemplateData Fields

Field Type Description
ProductCatalogId string (GUID) Unique identifier for the Product catalog
CustomerCategoryId string (GUID) Unique identifier for the Customer Segment (if applicable)
CustomerCategoryName string/null Name of the Customer Segment (if applicable)
ProductCategoryId string (GUID) Unique identifier for the product category
ProductCategoryUrlName string URL name of the product category
ProductId string (GUID) Unique identifier for the Product
ProductName string Name of the Product
ProductExternalId string External identifier for the Product
TimestampUtc string (datetime) UTC timestamp when the offer visibility change occurred

Limitations

Sellers cannot modify webhook configurations for events that are managed at the distributor level without proper permissions. For example, for newly configured webhooks at the distributor level, Seller-level webhook settings will work independently. To modify distributor-level webhook configurations, Sellers currently need to submit a support request.

Summary

This article guides Sellers through the process of configuring webhooks to receive real-time notifications about platform events, understanding webhook payload structures, and implementing proper authentication. It emphasizes the importance of understanding common and specific field definitions for each webhook type and highlights the limitation regarding webhook configuration permissions at different organizational levels.

Was this article helpful?

1 out of 1 found this helpful

Articles in this section

Add comment

Please sign in to leave a comment.