Webhooks

LostChurn sends webhook events to your application when key recovery and campaign actions occur. Use webhooks to keep your systems in sync with recovery status, update your UI, or trigger custom workflows.

Webhook Endpoints

Configure webhook endpoints in the LostChurn dashboard under Settings > Webhooks. Each endpoint specifies:

• URL: The HTTPS endpoint on your server that receives events
• Events: Which event types to send (subscribe to all or select specific types)
• Signing secret: Used to verify payload authenticity

You can create multiple endpoints to route different event types to different services.

Event Types

Recovery Events

Campaign Events

Customer Events

Payment Events

Payload Format

All webhook payloads follow a consistent structure:

{
  "id": "evt_abc123def456",
  "type": "recovery.succeeded",
  "created_at": "2025-03-08T14:30:00Z",
  "data": {
    "recovery_id": "rec_789xyz",
    "payment_id": "pay_abc123",
    "customer_id": "cus_def456",
    "amount": 4999,
    "currency": "usd",
    "decline_code": "insufficient_funds",
    "decline_category": "soft_retry",
    "retry_count": 2,
    "recovered_at": "2025-03-08T14:30:00Z",
    "psp": "stripe"
  }
}

Common Fields

Recovery Event Data

Campaign Event Data

Signature Verification

Every webhook request includes a signature header that you should verify to ensure the payload was sent by LostChurn and has not been tampered with.

Headers

Verification Process

1. Read the X-LostChurn-Timestamp and X-LostChurn-Signature headers.
2. Concatenate the timestamp and the raw request body with a . separator: {timestamp}.{body}.
3. Compute an HMAC-SHA256 hash using your webhook signing secret.
4. Compare the computed hash to the signature header using a constant-time comparison.
5. Verify the timestamp is within 5 minutes of your server's current time.

Node.js Verification Example

import crypto from "node:crypto";

function verifyLostChurnWebhook(req, signingSecret) {
  const signature = req.headers["x-lostchurn-signature"];
  const timestamp = req.headers["x-lostchurn-timestamp"];
  const body = req.rawBody; // raw request body as string

  // Check timestamp tolerance (5 minutes)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp)) > 300) {
    throw new Error("Webhook timestamp outside tolerance window");
  }

  // Compute expected signature
  const payload = `${timestamp}.${body}`;
  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(payload)
    .digest("hex");

  // Constant-time comparison
  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  );

  if (!isValid) {
    throw new Error("Invalid webhook signature");
  }

  return JSON.parse(body);
}

Python Verification Example

import hmac
import hashlib
import time
import json

def verify_lostchurn_webhook(headers, body, signing_secret):
    signature = headers["X-LostChurn-Signature"]
    timestamp = headers["X-LostChurn-Timestamp"]

    # Check timestamp tolerance (5 minutes)
    now = int(time.time())
    if abs(now - int(timestamp)) > 300:
        raise ValueError("Webhook timestamp outside tolerance window")

    # Compute expected signature
    payload = f"{timestamp}.{body}".encode("utf-8")
    expected = hmac.new(
        signing_secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()

    # Constant-time comparison
    if not hmac.compare_digest(expected, signature):
        raise ValueError("Invalid webhook signature")

    return json.loads(body)

Retry Policy

If your endpoint returns a non-2xx status code or does not respond within 30 seconds, LostChurn retries the delivery:

After 3 failed retries (4 total attempts), the event is marked as failed. Failed events can be viewed and manually retried from Settings > Webhooks > Failed Events in the dashboard.

Inbound Webhook Deduplication

When LostChurn receives webhooks from your payment processor, duplicate events are automatically rejected at the edge. The deduplication layer uses a 24-hour sliding window keyed on the event ID from the payment processor (e.g., Stripe's evt_ ID). If the same event arrives twice — whether from a processor retry, a network hiccup, or a misconfigured endpoint — the second delivery is acknowledged with a 200 response but silently discarded.

This means your recovery pipeline never processes the same payment failure twice, even if your processor delivers the event multiple times.

Webhook Payload Storage

Raw inbound webhook payloads are stored encrypted in Cloudflare R2 (AES-256-GCM) for up to 548 days. This retention window covers the full Visa and Mastercard chargeback dispute period.

Stored payloads serve two purposes:

• Dispute evidence — If a customer disputes a recovered charge, the original failure event and all subsequent recovery actions are available as evidence.
• Audit trail — For compliance and debugging, the exact payload received from the payment processor is preserved in its original form.

Best Practices

Testing Webhooks

You can send test webhook events from the dashboard:

1. Go to Settings > Webhooks and select an endpoint.
2. Click Send Test Event.
3. Select the event type.
4. Click Send. The test event is delivered to your endpoint with a test: true field in the payload.

For local development, use a tunneling service like ngrok to expose your local server:

ngrok http 8080

Then configure the ngrok URL as a webhook endpoint in LostChurn.

Next Steps

• Authentication -- webhook signing secrets and key management
• Payments -- query and retry payments via the API
• Webhook Verification (Security) -- inbound webhook verification from PSPs