Web Hooks
Configure web hooks to notify your server about subscription changes.
Applies only to subscription-based products that rely upon a server component.
The Web Hooks solution complements the Muse SDK. This feature allows our system to proactively notify your server component about any changes in subscription status in real-time. When a subscription status update occurs, our system will send a POST request to a predetermined endpoint on your server, containing the updated information, including the UUID associated with the subscription. This approach not only ensures that you receive timely updates, but also provides an additional layer of verification. By cross-referencing the UUID received through the Web Hook with the one obtained via the Muse SDK, you can confidently confirm the subscription status changes.
Creating web hooks
Web Hooks are configured in the Muse Partner Portal.
In the left pane, head to Developer > Web Hooks. By clicking Add you can add a Customer Subscription Updated event and specify the endpoint on your server, for instance https://example.com:4005/my-endpoint
.
The web hook can be activated or deactivated anytime via the Active toggle switch on this page.
After saving the web hook, you'll receive a secret key
that is needed to securely authenticate the received data on your server. This secret can be rotated at your convenience via the dedicated Rotate secret button, for added security.
From this page, you can also test the endpoint implementation on your server via the handy Send test event button. Just fill in the message data and click Send.
Events and payloads
Each web hook event carries data for one of more subscription changed events and is protected by an authenticated signature.
Notification format
Following is an example of a webhook POST request in JSON format.
Body parameters:
UUID
: Unique User ID, as returned by the Muse SDK (max 32 bytes).product_id
of the product for which the notification was triggered, visible in the product page on the Muse Partner Portal.SKU
is a custom mnemonic field for your convenience. You can optionally provide it in the product page on the Muse Partner Portal.subscription_option
is also an optional text field associated with a subscription type that you can provide for each subscription on the Muse Partner Portal. This will allow you to discern the plan and also upgrades / downgrades if you have more than one type.event_type
depends on the trigger and can be any string ofTrialStarted
,TrialExpired
,SubscriptionRenewed
(also for first subscription start),SubscriptionCancelled
(continue until original renewal date),SubscriptionRefunded
(terminate immediately, also comprises any other immediate cancellations related to failed or disputed payment).event_time
always refers to the instant the notification triggered (UTC).next_event_time
is also a datetime UTC that depends onevent_type
:TrialStarted
: future time of trial expiryTrialExpired
: n.a.SubscriptionRenewed
: next renewal timeSubscriptionCancelled
: original expiry time of current subscription plan (continue till the end)SubscriptionRefunded
: same asevent_time
(immediate suspension)
Message validation
HTTP POST payloads that are delivered to your configured URL endpoint will contain an Authorization
header like this one:
This is the HMAC hex digest of the request body, and is generated using the SHA-256 hash function and the previously described secret key
displayed in the Partner Portal as the HMAC key. By calculating the HMAC on the request body and comparing your result against the Signature
value, you ensure the authenticity of the received data. It is possible to calculate the HMAC using common functions provided by server-side languages, for instance node.jsâ crypto.createHmac
.
Delivery
Whenever a subscription event happens, our system will send a POST notification to the endpoint you specified. Your server shall reply with a 200 status code to confirm reception.
In case of failed deliveries (i.e. your server is busy or unreachable), our system will retry sending with an exponential backoff time configured as follows: interval=10s, max retries=40, exponential=1.25 (~20 attempts in the first hour, stops after ~3 days).
Last updated