Webhooks

Mantle currently provides a range of webhooks to deliver important notifications regarding activity within your app.

Event	Description
Plan created plans/create	Triggered when a new plan is generated.
Plan updated plans/update	Triggered when an existing plan undergoes updates.
Subscription activated subscriptions/activate	Triggered when a new subscription is initiated.
Subscription cancelled subscriptions/cancel	Triggered when a subscription is terminated.
Subscription approaching capped amount subscriptions/approaching_capped_amount	Triggered when the customer reaches 90% of their usage cap. Shopify sends an email to the merchant at this point to notify them.
Subscription usage charge exceeds capped amount subscriptions/usage_charge_exceeds_limit	Triggered when the charge for a subscription surpasses the amount merchants have previously agreed upon.
Subscription capped amount updated subscriptions/capped_amount_updated	Triggered when the merchant updates the capped amount, through the Shopify Admin interface or the Mantle API.
One-time charge activated one_time_charges/activate	Triggered when a one-time charge is activated.
Customer installed app customers/installed	Triggered when a customer installs this app for the first time.
Customer uninstalled app customers/uninstalled	Triggered when a customer uninstalls this app.
Customer reinstalled app customers/reinstalled	Triggered when a customer reinstalls this app.
Customer deactivated app customers/deactivated	Triggered when a customer has their account deactivated on the platform.
Customer reactivated app customers/reactivated	Triggered when a customer has their account reactivated on the platform
Customer trial expired customers/trial_expired	Triggered when a customer has their trial expired with the app or subscription
Customer first-time identify customers/first_identify	Triggered the first time the customer is identified with the Mantle App API

To subscribe to a webhook:

Click on the app you’d like to use from Mantle’s left navigation.
Navigate to Settings in the top right-hand corner.
Select API keys.
Click on Add webhook.
Choose the webhook you’d like and enter the URL where you’d like to receive it.

Verifying webhooks

The webhooks are signed using HMAC SHA256 in the X-Mantle-Hmac-SHA256 header. The signing data consists of the X-Timestamp header concatenated with the stringified JSON payload: timestamp.payload.

The secret will be the api key if the webhook is an app-specific webhook, or the secret if the webhook is a notification webhook.

Javascript example

const crypto = require('crypto');

const verifySignature = (secret, data, expectedSignature) => {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(data, 'utf8');
  const calculatedSignature = hmac.digest('hex');
  return crypto.timingSafeEqual(Buffer.from(calculatedSignature), Buffer.from(expectedSignature));
}

const secret = # api key or secret
const timestamp = # X-Timestamp header
const expectedSignature = # X-Mantle-Hmac-SHA256 header
const body = # raw body of the webhook

const data = `${timestamp}.${body}`;
const isValid = verifySignature(secret, data, expectedSignature);

PHP example

function verifySignature($secret, $data, $expectedSignature) {
    $calculatedSignature = hash_hmac('sha256', $data, $secret);
    return hash_equals($calculatedSignature, $expectedSignature);
}

$secret = # api key or secret
$timestamp = # X-Timestamp header
$expectedSignature = # X-Mantle-Hmac-SHA256 header
$body = # raw body of the webhook

$data = $timeStamp . "." . $body;
$isValid = verifySignature($secret, $data, $expectedSignature);