Ctrlk
Partner Portal
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Web Hooks

Configure web hooks to notify your server about subscription changes.

Applies to products that rely upon a server component, for subscription updates and for purchases and refunds.

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.

Currently, two types of webhooks can be configured: "Customer subscription updated" and "Product purchase/refund".

Notification format

Here are examples of webhook POST requests. The body is sent as compact JSON on a single line, exactly as shown, and the signatures were computed with the example secret 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef, so you can use them to test your validation code.

Type: Customer subscription updated

Type: Product purchase/refund

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 of:

    • <EVENT_TYPE_SUB>: TrialStarted, 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_TYPE_PROD>: Purchased or Refunded

  • product_version_type can be Release or Beta according to the product type triggering the event. This allows to simulate purchases and refunds by adding or removing users to/from private Beta groups and discerning them from non-test events.

  • event_time always refers to the instant the notification triggered (UTC).

  • next_event_time is also a datetime UTC that depends on event_type:

    • TrialStarted : future time of trial expiry

    • TrialExpired : n.a.

    • SubscriptionRenewed : next renewal time

    • SubscriptionCancelled : original expiry time of current subscription plan (continue till the end)

    • SubscriptionRefunded : same as event_time (immediate suspension)

Additionally, for subscribing or purchasing users who have opted-in to sharing their contact with developers, the two webhook notifications above may contain the following additional fields: email , name , picture_url.

Message validation

HTTP POST payloads that are delivered to your configured URL endpoint will contain an Authorization header like this one:

The signature is the base64-encoded HMAC-SHA256 of the request body. The HMAC key is the secret key displayed in the Partner Portal, used as a plain string: don't hex-decode it. Compute the HMAC over the raw request body exactly as received, before any JSON parsing, since re-serialising the JSON changes the bytes and the signature won't match. Then compare your result against the Signature value to confirm the authenticity of the received data. For example, in node.js:

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).

PreviousURI Protocol
NextIntegration FAQs

Last updated