Overview

When a relevant event happens in Churn Solution — for example, a customer completes a cancellation flow — we send an HTTP POST request to the endpoint URL you have registered with us. The body is JSON, and a cryptographic signature is included in a header so you can verify the payload genuinely came from Churn Solution.

You will be provided with a signing secret for each registered endpoint. Keep it secret — it is the only thing that lets you prove a payload is authentic.

Endpoint requirements

Your endpoint must:

1. Be reachable over HTTPS at a stable, publicly accessible URL.
2. Accept a JSON POST body.
3. Respond with a 2xx status code once the event has been received and stored. Any 4xx/5xx response is treated as a failed delivery.
4. Respond quickly. Acknowledge receipt first, then do heavy processing asynchronously.

Request format

Every webhook is delivered with this top-level envelope:

{
  "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

session — Cancellation-flow session

Sent when a customer completes a cancellation-flow session. The data.object is "session" and the data.session object is populated. This is currently the primary business event.

The Session object

data.session describes a customer's journey through a cancellation flow and its outcome.

{
  "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

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 array describing each step the customer encountered, in display order. Each step has a type, and the fields relevant to that type are populated.

{
  "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, indicating the kind of offer made.

Coupon

Verifying signatures

Every request includes a Churnsolution-Signature header. It is a hex-encoded HMAC-SHA256 of the payload, keyed with your endpoint's signing secret.

How the signature is computed

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

• <created_at> is the integer value of the top-level created_at field in the body.
• <raw_request_body> is the exact, unmodified raw bytes of the request body. Do not re-serialize the parsed JSON — whitespace and key ordering must match exactly.
• The two parts are joined by a single semicolon (;).

Verification steps

1. Read the raw request body as received (before any JSON parsing or reformatting).
2. Read the created_at value from the body.
3. Compute HMAC_SHA256(signing_secret, created_at + ";" + raw_body) and hex-encode it.
4. Compare your result to the Churnsolution-Signature header using a constant-time comparison.
5. Reject the request (401) if they do not match.

Node.js (Express)

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

Python (Flask)

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

• Success is any non-error HTTP response (2xx/3xx). A 4xx/5xx, a connection error, or a timeout is recorded as a failed delivery.
• The attempt_number field indicates the delivery attempt for this event.
• Idempotency: the same logical event may be delivered more than once. De-duplicate using the top-level id so you process each event exactly once.
• Ordering: do not assume webhooks arrive in the order events occurred. Use created_at to order events if needed.

Best practices

• Always verify the signature before acting on a payload.
• Respond fast (2xx) and process asynchronously.
• Be tolerant of new fields. We may add fields over time; ignore unknown fields rather than failing.
• Treat fields as nullable. Optional fields may be null or absent depending on the scenario.
• Keep your signing secret secret. Store it in a secrets manager or environment variable, never in client-side code.
• Use HTTPS so payloads are encrypted in transit.

Quick reference