Purchasely can send real-time Server Events to your backend via a webhook. These events cover every stage of the subscription lifecycle — from activation to renewal, plan changes, billing issues, and churn.

This page explains how to configure and implement the webhook to receive Lifecycle Events, Offer Events and Transactional Events.

📘

Looking for entitlement management?

If you want to use the webhook to manage user entitlements (ACTIVATE / DEACTIVATE events), refer to the dedicated guide: Backend Entitlements.

Benefits

Receiving server events on your backend unlocks several capabilities:

• Marketing automations — Trigger campaigns based on lifecycle milestones (e.g. send a win-back email when RENEWAL_DISABLED fires, or a congratulations message on TRIAL_CONVERTED)
• Data pipeline — Feed your data warehouse, BI tools or analytics platforms with granular subscription data for cohort analysis, churn prediction and LTV modeling
• Internal tooling — Power customer support dashboards with real-time subscription status, billing issue alerts and transaction history
• Revenue tracking — Use TRANSACTION_PROCESSED events to reconcile revenue across stores and currencies in your own systems
• Server Event forwarding — If you rely on a 3rd party platform which is not natively supported by Purchasely, you can leverage the webhook to receive the events and forward them directly to your 3rd-party platform directly from your backend

Configuration

Setting up the webhook requires two steps in the Purchasely Console under [YOUR APP] > Settings > Webhooks.

1. Set your endpoint URL

Enter your Client webhook URL — this is the HTTPS endpoint on your backend that will receive the events.

2. Enable Subscription Events

Scroll down to the Subscription events section. Here you can toggle individual events on or off depending on your needs.

Events are organized by category:

For a complete list and description of each event, see:

• Lifecycle Events
• Offer Events
• Transactional Event

📘

Event acknowledgement expected

As soon as you have configured a Client webhook URL, the Purchasely Platform will expect an acknowledgement for all events sent on the webhook.

You can start by implementing a simple HTTP 200 response for every message sent on the webhook.

Implementation

1. Receive and acknowledge events

Your endpoint will receive POST requests with a JSON payload for each event. The most important rule: always return HTTP 200 to acknowledge the event.

2. Route events based on event_name

Each payload includes an event_name field that identifies the event type. Use it to route the event to the appropriate handler in your backend.

const express = require('express');
const app = express();
app.use(express.json());

app.post('/purchasely/webhook', (req, res) => {
  const event = req.body;

  switch (event.event_name) {
    // Lifecycle events
    case 'SUBSCRIPTION_STARTED':
    case 'SUBSCRIPTION_RENEWED':
    case 'SUBSCRIPTION_TERMINATED':
    case 'RENEWAL_DISABLED':
      handleLifecycleEvent(event);
      break;

    // Offer events
    case 'TRIAL_STARTED':
    case 'TRIAL_CONVERTED':
    case 'TRIAL_NOT_CONVERTED':
      handleOfferEvent(event);
      break;

    // Transaction event
    case 'TRANSACTION_PROCESSED':
      handleTransactionEvent(event);
      break;

    // Entitlement events (see Backend Entitlements guide)
    case 'ACTIVATE':
    case 'DEACTIVATE':
      handleEntitlementEvent(event);
      break;

    default:
      console.log(`Unhandled event: ${event.event_name}`);
  }

  // Always acknowledge
  res.status(200).send('OK');
});

# Uses Sinatra
post '/purchasely/webhook' do
  payload = JSON.parse(request.body.read)

  case payload['event_name']
  when 'SUBSCRIPTION_STARTED', 'SUBSCRIPTION_RENEWED',
       'SUBSCRIPTION_TERMINATED', 'RENEWAL_DISABLED'
    handle_lifecycle_event(payload)
  when 'TRIAL_STARTED', 'TRIAL_CONVERTED', 'TRIAL_NOT_CONVERTED'
    handle_offer_event(payload)
  when 'TRANSACTION_PROCESSED'
    handle_transaction_event(payload)
  when 'ACTIVATE', 'DEACTIVATE'
    handle_entitlement_event(payload) # See Backend Entitlements guide
  else
    puts "Unhandled event: #{payload['event_name']}"
  end

  # Always acknowledge
  status 200
  body 'OK'
end

3. Extract relevant data from the payload

All server events share a common JSON structure. Key fields include:

For TRANSACTION_PROCESSED events, additional revenue fields are provided (store_price, customer_currency, plan_price_in_customer_currency, etc.).

For the full payload reference, see Server Events Attributes.

4. Authenticate messages (recommended)

We strongly recommend verifying webhook signatures to protect your endpoint against spoofed requests.

const crypto = require("crypto");

// Request headers
// ---------------
const xPurchaselyRequestSignature = "f3c2a452e9ea72f41107321aeaf7999f1054148866a710c9b23f9f501785e2a4";
const xPurchaselyTimestamp = "1698322022";

// Request body
// ------------
// Please use the raw body and not an already parsed body.
// For example with Node:
//      DO: req.rawBody.toString()
//   DON'T: JSON.stringify(req.body)
const body = "{\"a_random_key\":\"a_random_value_ad\"}";

// Signature verification
// ----------------------
const webhookSharedSecret = "foobar";
const dataToSign = xPurchaselyTimestamp + body;
const computedSignature = crypto
                          .createHmac("sha256", webhookSharedSecret)
                          .update(dataToSign)
                          .digest("hex");

if (computedSignature === xPurchaselySignature) {
  // request authenticated
}

require 'openssl'

# Request headers
# ---------------
x_purchasely_signature = "f3c2a452e9ea72f41107321aeaf7999f1054148866a710c9b23f9f501785e2a4"
x_purchasely_timestamp = "1698322022"

# Request body
# ------------
# Please use the raw body and not an already parsed body.
# For example with Ruby on Rails: request.raw_post
body = "{\"a_random_key\":\"a_random_value_ad\"}"

# Signature verification
# ----------------------
webhook_shared_secret = "foobar"
data_to_sign = x_purchasely_timestamp + body
computed_signature = OpenSSL::HMAC.hexdigest('sha256', webhook_shared_secret, data_to_sign)

if (computed_signature == x_purchasely_signature) {
  # request authenticated
}

// Imports
// -------
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec

// Request headers
// ---------------
val xPurchaselySignature = "f3c2a452e9ea72f41107321aeaf7999f1054148866a710c9b23f9f501785e2a4"
val xPurchaselyTimestamp = "1698322022"

// Request body
// ------------
// Please use the raw body and not an already parsed body.
val body = "{\"a_random_key\":\"a_random_value_ad\"}"

// Signature verification
// ----------------------
val webhookSharedSecret = "foobar"
val dataToSign = xPurchaselyTimestamp + body
val hmac = Mac.getInstance("HmacSHA256")
hmac.init(SecretKeySpec(webhookSharedSecret.toByteArray(), "HmacSHA256"))
val computedSignature = hmac.doFinal(dataToSign.toByteArray()).joinToString("") { "%02x".format(it) }

if (computedSignature == xPurchaselySignature) {
    // request authenticated
}

For more details, see Webhook Messages Authentication.