Implementace webhooku ve službě SaaS

Článek
01/31/2025

Při vytváření nabídky SaaS s možností transakce v Partnerském centru poskytuje partner webhook Connection adresu URL, která se má použít jako koncový bod HTTP. Tento webhook volá Společnost Microsoft pomocí volání POST HTTP, která informuje vydavatele o následujících událostech, ke kterým dochází na straně Microsoftu:

Událost Webhooku	1. Při přijetí	2. Je-li přijato	3. Pokud byl odmítnut
`ChangePlan`	Odpověď pomocí HTTP 200	PATCH s úspěchem (tato událost je volitelná a automaticky se vyčte v 10 sekundách)	PATCH s chybou NEBO odpovězte na 4xx (do 10 sekund)
`ChangeQuantity`	Odpověď pomocí HTTP 200	PATCH s úspěchem (tato událost je volitelná a automaticky se vyčte v 10 sekundách)	PATCH s chybou NEBO odpovězte na 4xx (do 10 sekund)
`Renew`	Odpověď pomocí HTTP 200	Nejde použít	Nejde použít
`Suspend`	Odpověď pomocí HTTP 200	Nejde použít	Nejde použít
`Unsubscribe`	Odpověď pomocí HTTP 200	Nejde použít	Nejde použít
`Reinstate`	Odpověď pomocí HTTP 200	Nejde použít	Nejde použít (pokud není možné přijmout obnovení, volání rozhraní API pro odstranění, které aktivuje odstranění)

Vydavatel musí ve službě SaaS implementovat webhook, aby byl stav předplatného SaaS konzistentní se stranou Microsoftu. Služba SaaS je nutná k volání rozhraní API operace Get, aby bylo před provedením akce na základě oznámení webhooku ověřeno a autorizováno volání webhooku a dat datové části webhooku. Jakmile bude volání webhooku zpracováno, vydavatel by měl microsoftu vrátit http 200. Tato hodnota potvrzuje, že volání webhooku bylo úspěšně přijato vydavatelem.

Důležitý

Služba URL webhooku musí být spuštěná a spuštěná 24 × 7 a je připravená přijímat nová volání od Microsoftu vždy. Microsoft má zásady opakování pro volání webhooku (500 opakovaných pokusů za osm hodin), ale pokud vydavatel hovor nepřijme a vrátí odpověď, operace, o které webhook upozorní, nakonec selže na straně Microsoftu.

Důležitý

Nezávislí výrobci softwaru by se měli vyhnout přísné deserializaci schématu Webhooku. Společnost Microsoft si vyhrazuje právo rozšířit schéma v budoucnu.

Důležitý

Nezávislí výrobci softwaru musí z hlavičky požadavku ověřit token Microsoft Entra Token (JWT Token) ve svém koncovém bodu webhooku. Jedná se o standardní nosný token a poskytne isV podrobnosti o tom, kdo volající je. Další informace o ověření tokenu najdete v tomto článku. learn.microsoft.com/azure/active-directory/develop/access-tokens

Příklad datové části webhooku ChangePlan:

{
    "id": "<guid>",
    "activityId": "<guid>",
    "publisherId": "XXX",
    "offerId": "YYY",
    "planId": "plan2",
    "quantity": 10,
    "subscriptionId": "<guid>",
    "timeStamp": "2023-02-10T18:48:58.4449937Z",
    "action": "ChangePlan",
    "status": "InProgress",
    "operationRequestSource": "Azure",
    "subscription":
    {
      "id": "<guid>",
      "name": "Test",
      "publisherId": "XXX",
      "offerId": "YYY",
      "planId": "plan1",
      "quantity": 10,
      "beneficiary":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "purchaser":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "allowedCustomerOperations": ["Delete", "Update", "Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Subscribed",
      "term":
        {
          "startDate": "2022-02-10T00:00:00Z",
          "endDate": "2022-03-12T00:00:00Z",
          "termUnit": "P1M",
          "chargeDuration": null,
        },
      "autoRenew": true,
      "created": "2022-01-10T23:15:03.365988Z",
      "lastModified": "2022-02-14T20:26:04.5632549Z",
    },
    "purchaseToken": null
}

příklad datové části Webhooku události ChangeQuantity:


{
    "id": "<guid>",
    "activityId": "<guid>",
    "publisherId": "XXX",
    "offerId": "YYY",
    "planId": "plan1",
    "quantity": 20,
    "subscriptionId": "<guid>",
    "timeStamp": "2023-02-10T18:54:00.6158973Z",
    "action": "ChangeQuantity",
    "status": "InProgress",
    "operationRequestSource": "Azure",
    "subscription": {
        "id": "<guid>",
        "name": "Test",
        "publisherId": "XXX",
        "offerId": "YYY",
        "planId": "plan1",
        "quantity": 10,
        "beneficiary":
            {
            "emailId": XX@outlook.com,
            "objectId": "<guid>",
            "tenantId": "<guid>",
            "puid": "1234567890",
            },
        "purchaser":
            {
            "emailId": XX@outlook.com,
            "objectId": "<guid>",
            "tenantId": "<guid>",
            "puid": "1234567890",
            },
        "allowedCustomerOperations": ["Delete", "Update", "Read"],
        "sessionMode": "None",
        "isFreeTrial": false,
        "isTest": false,
        "sandboxType": "None",
        "saasSubscriptionStatus": "Subscribed",
        "term":
            {
            "startDate": "2022-02-10T00:00:00Z",
            "endDate": "2022-03-12T00:00:00Z",
            "termUnit": "P1M",
            "chargeDuration": null,
            },
        "autoRenew": true,
        "created": "2022-01-10T23:15:03.365988Z",
        "lastModified": "2022-02-14T20:26:04.5632549Z",
    },
    "purchaseToken": null
}

příklad datové části webhooku události obnovení předplatného:

// end user's payment instrument became valid again, after being suspended, and the SaaS subscription is being reinstated


{
    "id": "<guid>",
    "activityId": "<guid>",
    "publisherId": "XXX",
    "offerId": "YYY",
    "planId": "plan1",
    "quantity": 100,
    "subscriptionId": "<guid>",
    "timeStamp": "2023-02-11T11:38:10.3508619Z",
    "action": "Reinstate",
    "status": "InProgress",
    "operationRequestSource": "Azure",
    "subscription":
    {
      "id": "<guid>",
      "name": "Test",
      "publisherId": "XXX",
      "offerId": "YYY",
      "planId": "plan1",
      "quantity": 100,
      "beneficiary":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "purchaser":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "allowedCustomerOperations": ["Delete", "Update", "Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended",
      "term":
        {
          "startDate": "2022-02-10T00:00:00Z",
          "endDate": "2022-03-12T00:00:00Z",
          "termUnit": "P1M",
          "chargeDuration": null,
        },
      "autoRenew": true,
      "created": "2022-01-10T23:15:03.365988Z",
      "lastModified": "2022-02-14T20:26:04.5632549Z",
    },
    "purchaseToken": null
}

příklad datové části webhooku události prodloužení:

// end user's subscription renewal
 
{
    "id": "<guid>",
    "activityId": "<guid>",
    "publisherId": "XXX",
    "offerId": "YYY",
    "planId": "plan1",
    "quantity": 100,
    "subscriptionId": "<guid>",
    "timeStamp": "2023-02-10T08:49:01.8613208Z",
    "action": "Renew",
    "status": "Succeeded",
    "operationRequestSource": "Azure",
    "subscription":
    {
      "id": "<guid>",
      "name": "Test",
      "publisherId": "XXX",
      "offerId": "YYY",
      "planId": "plan1",
      "quantity": 100,
      "beneficiary":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "purchaser":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "allowedCustomerOperations": ["Delete", "Update", "Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Subscribed",
      "term":
        {
          "startDate": "2022-02-10T00:00:00Z",
          "endDate": "2022-03-12T00:00:00Z",
          "termUnit": "P1M",
          "chargeDuration": null,
        },
      "autoRenew": true,
      "created": "2022-01-10T23:15:03.365988Z",
      "lastModified": "2022-02-14T20:26:04.5632549Z",
    },
  "purchaseToken": null,
}

příklad datové části Webhooku události pozastavení:


{
    "id": "<guid>",
    "activityId": "<guid>",
    "publisherId": "XXX",
    "offerId": "YYY",
    "planId": "plan1",
    "quantity": 100,
    "subscriptionId": "<guid>",
    "timeStamp": "2023-02-10T08:49:01.8613208Z",
    "action": "Suspend",
    "status": "Succeeded",
    "operationRequestSource": "Azure",
    "subscription":
    {
      "id": "<guid>",
      "name": "Test",
      "publisherId": "XXX",
      "offerId": "YYY",
      "planId": "plan1",
      "quantity": 100,
      "beneficiary":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "purchaser":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "allowedCustomerOperations": ["Delete", "Update", "Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Suspended",
      "term":
        {
          "startDate": "2022-02-10T00:00:00Z",
          "endDate": "2022-03-12T00:00:00Z",
          "termUnit": "P1M",
          "chargeDuration": null,
        },
      "autoRenew": true,
      "created": "2022-01-10T23:15:03.365988Z",
      "lastModified": "2022-02-14T20:26:04.5632549Z",
    },
  "purchaseToken": null,
}

Příklad datové části webhooku události odhlášení odběru:

Jedná se o událost, která je určena pouze pro upozornění. Pro tuto událost neexistuje odeslání do ACK.


{
    "id": "<guid>",
    "activityId": "<guid>",
    "publisherId": "XXX",
    "offerId": "YYY",
    "planId": "plan1",
    "quantity": 100,
    "subscriptionId": "<guid>",
    "timeStamp": "2023-02-10T08:49:01.8613208Z",
    "action": "Unsubscribe",
    "status": "Succeeded",
    "operationRequestSource": "Azure",
    "subscription":
    {
      "id": "<guid>",
      "name": "Test",
      "publisherId": "XXX",
      "offerId": "YYY",
      "planId": "plan1",
      "quantity": 100,
      "beneficiary":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "purchaser":
        {
          "emailId": XX@outlook.com,
          "objectId": "<guid>",
          "tenantId": "<guid>",
          "puid": "1234567890",
        },
      "allowedCustomerOperations": ["Delete", "Update", "Read"],
      "sessionMode": "None",
      "isFreeTrial": false,
      "isTest": false,
      "sandboxType": "None",
      "saasSubscriptionStatus": "Unsubscribed",
      "term":
        {
          "startDate": "2022-02-10T00:00:00Z",
          "endDate": "2022-03-12T00:00:00Z",
          "termUnit": "P1M",
          "chargeDuration": null,
        },
      "autoRenew": true,
      "created": "2022-01-10T23:15:03.365988Z",
      "lastModified": "2022-02-14T20:26:04.5632549Z",
    },
  "purchaseToken": null,
}

Zabezpečení webhooků

Webhooky je nutné zabezpečit, aby žádné jiné než koncové body Microsoftu takové volání Webhooku nevolají. K implementaci webhooků můžete použít libovolnou technologii, ale implementace Webhooku musí dodržovat následující pokyny zabezpečení (viz kurz).

Microsoft volá webhooky s autorizačními hlavičkami, které obsahují potřebné informace k ověření volání. Aby webhooky mohly přijímat autorizační hlavičky, musíte povolit. (Nepřidávejte podrobnosti o autorizaci ani tokeny zabezpečení, jako jsou tokeny SAS, přímo do adres URL webhooku. Takové webhooky se nemusí podařit načíst autorizační hlavičky, které Microsoft odesílá při volání webhooků).
Nosný token JWT předaný v autorizační hlavičce obsahuje následující data v datové části, která můžete použít k zabezpečení koncových bodů.
"aud": "toto je ID aplikace Microsoft Entra Identity, které přidáte do technické konfigurace vaší nabídky v Partnerském centru Microsoftu"
"appid" nebo "azp": Toto je ID prostředku, které používáte při vytváření autorizačního tokenu vydavatele pro volání rozhraní API pro plnění SaaS. V závislosti na nastavení aplikace se tato hodnota ID prostředku může zobrazit buď v "appid" nebo "azp". Token má jednu ze dvou deklarací identity a v kódu musíte odpovídajícím způsobem reagovat.
"tid": "toto je ID tenanta Microsoft Entra, které přidáte do technické konfigurace vaší nabídky v Partnerském centru Microsoftu"
Zkontrolujte výše uvedená předaná pole a ujistěte se, že volání Webhooku je platné.

Důležitý

Společnost Microsoft začne vyžadovat nezávislé výrobce softwaru, aby vytvořili své webhooky zabezpečeným způsobem a přijali autorizační hlavičky. Pokud vaše aktuální implementace Webhooku nemůže přijmout autorizační hlavičky, musíte aktualizovat webhooky a zabezpečit tyto koncové body (pomocí výše uvedených pokynů), aby nedošlo k přerušení.

Vývoj a testování

Pokud chcete zahájit proces vývoje, doporučujeme na straně vydavatele vytvářet fiktivní odpovědi rozhraní API. Tyto odpovědi mohou být založeny na ukázkových odpovědích uvedených v tomto článku.

Až bude vydavatel připravený na kompletní testování:

Publikujte nabídku SaaS pro omezenou cílovou skupinu ve verzi Preview a ponechte ji ve fázi Preview.
Nastavte cenu plánu na nulu, abyste se vyhnuli aktivaci skutečných fakturačních výdajů při testování. Další možností je nastavit nenulovou cenu a zrušit všechny testovací nákupy do 24 hodin.
Ujistěte se, že jsou všechny toky vyvolány na konci, aby simulovaly scénář skutečného zákazníka.
Pokud chce partner otestovat úplný nákup a tok fakturace, udělejte to s nabídkou, která má cenu vyšší než 0 USD. Nákup se fakturuje a vygeneruje se faktura.

Tok nákupu se dá aktivovat z webu Azure Portal nebo webu Microsoft AppSource v závislosti na tom, kde se nabídka publikuje.

změnit plán, změnit množstvía odhlásit odběr akcí jsou testovány na straně vydavatele. Na straně Microsoftu odhlášení odběru je možné aktivovat na webu Azure Portal i v Centru pro správu (portál, kde se spravují nákupy Microsoft AppSource). Změnit množství a plán se dají aktivovat jenom z Centra pro správu.

Získání podpory

Možnosti podpory vydavatele najdete v tématu Podpora pro program komerčního marketplace v Partnerském centru.

Další možnosti nabídek SaaS na komerčním marketplace na komerčním marketplace najdete v rozhraní API služby měření komerčního marketplace.
Projděte si a použijte klienty pro různé programovací jazyky a ukázky.
Podívejte se na následující videokursy:
- přehled SaaS Webhook
- implementace jednoduchého webhooku SaaS v .NET
- registrace aplikací Microsoft Entra

Sdílet prostřednictvím

Implementace webhooku ve službě SaaS

Zabezpečení webhooků

Vývoj a testování

Získání podpory

Váš názor

Další materiály

Sdílet prostřednictvím

Implementace webhooku ve službě SaaS

Zabezpečení webhooků

Vývoj a testování

Získání podpory

Související obsah

Váš názor

Další materiály