Webhooks

Churn Solution sends real-time notifications when key events occur in your account. This guide covers how events are generated, the structure of each payload, and how to verify that every request came from Churn Solution.

Overview

When a relevant event occurs — such as a customer completing a cancellation flow — Churn Solution sends an HTTP POST request to your registered endpoint. The body is JSON, and a signature in the request headers lets you confirm the sender.

Each registered endpoint receives its own signing secret. Keep it private — it is what proves a payload is authentic.

Endpoint requirements

1. Serve over HTTPS

   At a stable, public URL.

2. Accept a JSON POST body

   The request is sent as application/json.

3. Return a 2xx status

   Once the event is stored. Any 4xx or 5xx counts as a failed delivery.

4. Respond quickly

   Acknowledge receipt first and process heavy work asynchronously.

Request format

Every webhook uses the same top-level envelope: an event id, your app_id, a data object whose object field names the payload type, created_at and attempt_number.

{
  "id": 90217,
  "app_id": "your-app-identifier",
  "data": {
    "object": "session",
    "session": { /* see The Session object below */ }
  },
  "created_at": 1718971200,
  "attempt_number": 1
}

Request headers

Event types

Churn Solution currently sends one event type.

session — Cancellation-flow session

Sent when a customer completes a cancellation-flow session. data.object is "session", and data.session holds the Session object described below. This is the primary business event.

The Session object

The data.session object describes a customer's path through a cancellation flow and how it ended: the final status, whether the customer was saved, and nested customer, subscription, plan, flow, coupon and step details.

{
  "id": 12345,
  "status": "CANCELLED",
  "is_saved": false,
  "created_at": 1718971200,
  "customer": {
    "id": "cus_abc123",
    "name": "Jane Doe",
    "email": "[email protected]",
    "created_at": 1700000000
  },
  "subscription": {
    "id": "sub_abc123",
    "status": "ACTIVE",
    "start_date": 1700000000,
    "current_period_start": 1717200000,
    "current_period_end": 1719792000,
    "trial_start": null,
    "trial_end": null
  },
  "plan": {
    "id": "price_abc123",
    "recurring": { "interval": "month", "interval_count": 1 },
    "currency": "usd",
    "unit_amount": 2000,
    "unit_amount_decimal": 20.0,
    "quantity": 1,
    "plan_summary": "$20.00 / month"
  },
  "cancellation_flow": {
    "id": 55,
    "name": "Default Cancel Flow",
    "created_at": 1700000000,
    "updated_at": 1716000000
  },
  "uncancel_coupon": null,
  "steps": [ /* see Session steps below */ ]
}

status values

ABANDONED SEND_TO_PAGE CONTACT TRIAL_EXTENSION PAUSE SWITCH_PLAN COUPON CANCELLED PENDING_CANCEL UNCANCELLED UNPAUSED REACTIVATED SWITCH_PLAN_WITH_COUPON

Customer

Subscription

Subscription status values

ACTIVE TRIALING PAST_DUE PAUSED INCOMPLETE INCOMPLETE_EXPIRED CANCELED UNPAID EXPIRED PENDING HALTED ON_HOLD

Plan

Cancellation flow

Session steps

session.steps is an ordered array. Each step has a type; fields that do not apply to a step's type are null.

{
  "id": 9001,
  "type": "SURVEY",
  "order": 1,
  "contains_offer": true,
  "survey_answer": "Too expensive",
  "followup_question": "What price would work for you?",
  "followup_question_answer": "Around $10",
  "form_answer": null,
  "offer": {
    "accepted": true,
    "coupon": {
      "name": "Win-back 50%",
      "code": "STAY50",
      "currency": "usd",
      "amount_off": null,
      "amount_off_decimal": null,
      "percent_off": 50,
      "duration": "repeating",
      "duration_in_months": 3,
      "number_of_billing_cycles": 3,
      "currency_symbol": "$",
      "summary": "50% for 3 billing cycles"
    },
    "pause": null,
    "trial_extension": null
  }
}

Offer

Exactly one of coupon, pause or trial_extension is populated.

Coupon

Security

Verifying signatures

Each request carries a hex-encoded HMAC-SHA256 signature in the Churnsolution-Signature header, keyed with your endpoint's signing secret. Verify it with a constant-time comparison and reject mismatches with a 401.

How the signature is computed

signed_payload = "<created_at>;<raw_request_body>"
signature      = lowercase_hex( HMAC_SHA256( signing_secret, signed_payload ) )

Verification steps

1. Read the raw request body

   Before any parsing.

2. Extract created_at

   From the body.

3. Compute the HMAC-SHA256

   Over created_at, a semicolon, and the raw body, then hex-encode the result.

4. Compare

   Against the Churnsolution-Signature header using a constant-time comparison.

5. Reject mismatches

   Respond with 401.

const crypto = require('crypto');
const express = require('express');
const app = express();

const SIGNING_SECRET = process.env.CHURNSOLUTION_SIGNING_SECRET;

// Capture the raw body — required for signature verification.
app.post(
  '/webhooks/churnsolution',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const rawBody = req.body; // Buffer
    const signature = req.get('Churnsolution-Signature');

    const createdAt = JSON.parse(rawBody.toString()).created_at;
    const signedPayload = `${createdAt};${rawBody.toString()}`;

    const expected = crypto
      .createHmac('sha256', SIGNING_SECRET)
      .update(signedPayload)
      .digest('hex');

    const valid =
      signature &&
      expected.length === signature.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

    if (!valid) return res.status(401).send('Invalid signature');

    const event = JSON.parse(rawBody.toString());
    res.status(200).send('ok');   // acknowledge immediately
    handleEvent(event);           // process asynchronously
  }
);

import hmac, hashlib, json, os
from flask import Flask, request, abort

app = Flask(__name__)
SIGNING_SECRET = os.environ["CHURNSOLUTION_SIGNING_SECRET"]

@app.post("/webhooks/churnsolution")
def churnsolution_webhook():
    raw_body = request.get_data()  # raw bytes
    signature = request.headers.get("Churnsolution-Signature", "")

    created_at = json.loads(raw_body)["created_at"]
    signed_payload = f"{created_at};{raw_body.decode()}".encode()

    expected = hmac.new(
        SIGNING_SECRET.encode(), signed_payload, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(401)

    event = json.loads(raw_body)
    return "ok", 200

Delivery & retries

• Any 2xx or 3xx response counts as a successful delivery. 4xx / 5xx responses, connection failures and timeouts count as failures.
• attempt_number tells you which delivery attempt this is.
• The same event may be delivered more than once. De-duplicate using the top-level id.
• Events may arrive out of order. Use created_at to sort them if ordering matters.

Best practices

• Verify the signature before acting on any payload.
• Respond quickly; process asynchronously.
• Ignore unknown fields — new ones may be added over time.
• Treat optional fields as possibly null or absent.
• Store the signing secret in a secrets manager or environment variable, never in client-side code.
• Use HTTPS.

Quick reference