Webhooks

Mantle provides a range of webhooks to deliver notifications about important activity within your app. From plan changes to customer events, webhooks help you keep your systems in sync with what's happening in Mantle.

Setting up webhooks

To subscribe to a webhook:

Navigate to your app in Mantle's left navigation
Go to Settings in the sidebar
Select API keys
Click Add webhook
Choose your webhook and enter your endpoint URL

Available webhooks

Subscription plan events

Webhook Event	Description
`plans/create`	Triggered when a new subscription plan is created.
`plans/update`	Triggered when an existing subscription plan is modified.

Subscription lifecycle events

Webhook Event	Description
`subscriptions/activate`	Triggered when a customer activates a subscription.
`subscriptions/cancel`	Triggered when a customer cancels their subscription.
`subscriptions/upgrade`	Triggered when a customer upgrades to a higher-tier plan.
`subscriptions/downgrade`	Triggered when a customer downgrades to a lower-tier plan.
`subscriptions/billing_cycle_started`	Triggered when a new billing cycle begins.
`subscriptions/usage_approaching_cap`	Triggered when usage approaches the capped limit.

Customer events

Webhook Event	Description
`customers/installed`	Triggered when a customer installs your application.
`customers/uninstalled`	Triggered when a customer uninstalls your application.
`customers/reinstalled`	Triggered when a customer reinstalls your application.
`customers/deactivated`	Triggered when a customer's subscription is deactivated.
`customers/reactivated`	Triggered when a deactivated subscription is reactivated.
`customers/trial_expired`	Triggered when a customer's trial period ends without conversion.
`customers/first_identify`	Triggered when a customer is first identified.
`customers/features_updated`	Triggered when subscription features are updated.
`customers/trial_extended`	Triggered when a trial period is extended.
`custom_fields/updated`	Triggered when a custom field value is updated.
`one_time_charges/activate`	Triggered when a one-time charge is activated.

Verifying webhooks

All 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 for app-specific webhooks, or the secret for notification webhooks.

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

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