Webhooks

POST /hooks/chargetree HTTP/1.1
Content-Type: application/json
Chargetree-Signature: qDx0mB4kR7pY1sC8vN3tZ6wL9jH2fA5gE0uI7oP4qRs=
User-Agent: Chargetree-Webhooks/1.0

{
  "events": [
    {
      "event_id": "6c1f0e0f-2a4b-4f7d-9c3e-8b5a1d2e3f40",
      "resource_url": "https://manage.chargetree.co/api/v1/invoices/0b2c…",
      "resource_id": "0b2c…",
      "event_date_utc": "2026-07-15T04:21:33.482",
      "event_type": "Payment",
      "event_category": "INVOICE",
      "account": "9f8e…"
    }
  ]
}

export async function POST(request: Request): Promise<Response> {
  const rawBody = await request.text();

  // 1. Reject anything we cannot prove came from Chargetree.
  if (!isValidSignature(rawBody, request.headers.get('Chargetree-Signature'))) {
    return new Response('Invalid signature', { status: 401 });
  }

  const { events } = JSON.parse(rawBody);

  // 2. Hand off to a queue so we answer well inside the 15 second timeout.
  for (const event of events) {
    await enqueue(event);
  }

  return new Response('OK', { status: 200 });
}

{
  "events": [
    {
      "event_id": "6c1f0e0f-2a4b-4f7d-9c3e-8b5a1d2e3f40",
      "resource_url": "https://manage.chargetree.co/api/v1/invoices/0b2c8f1e-…",
      "resource_id": "0b2c8f1e-…",
      "event_date_utc": "2026-07-15T04:21:33.482",
      "event_type": "Payment",
      "event_category": "INVOICE",
      "account": "9f8e7d6c-…"
    }
  ]
}

{
  "events": [
    {
      "event_id": "b9d3a1c2-…",
      "resource_url": "https://manage.chargetree.co/api/v1/escalations/4e5f…",
      "resource_id": "4e5f…",
      "event_date_utc": "2026-07-15T04:21:33.482",
      "event_type": "Created",
      "event_category": "ESCALATION",
      "account": "9f8e7d6c-…",
      "escalation_type": "hardship",
      "priority": "high",
      "trigger_channel": "sms",
      "invoice_id": "0b2c8f1e-…",
      "contact_id": "7a6b5c4d-…"
    }
  ]
}

{
  "events": [
    {
      "event_id": "c8e4b2d3-…",
      "resource_url": "https://manage.chargetree.co/api/v1/escalations/4e5f…",
      "resource_id": "4e5f…",
      "event_date_utc": "2026-07-16T09:02:11.907",
      "event_type": "Resolved",
      "event_category": "ESCALATION",
      "account": "9f8e7d6c-…",
      "escalation_type": "hardship",
      "priority": "high",
      "trigger_channel": "sms",
      "invoice_id": "0b2c8f1e-…",
      "contact_id": "7a6b5c4d-…",
      "resolution_outcome": "payment_plan_agreed",
      "resolved_at": "2026-07-16T09:02:11.907Z"
    }
  ]
}

Chargetree-Signature: qDx0mB4kR7pY1sC8vN3tZ6wL9jH2fA5gE0uI7oP4qRs=

import { createHmac, timingSafeEqual } from 'node:crypto';

/**
 * Confirms a delivery was signed with our endpoint's secret.
 * Returns false rather than throwing, so a malformed header is simply rejected.
 */
function isValidSignature(rawBody: string, header: string | null): boolean {
  if (!header) return false;

  const expected = createHmac('sha256', process.env.CHARGETREE_WEBHOOK_SECRET!)
    .update(rawBody)
    .digest('base64');

  const received = Buffer.from(header, 'base64');
  const computed = Buffer.from(expected, 'base64');

  // timingSafeEqual throws if the lengths differ, so check that first.
  if (received.length !== computed.length) return false;

  return timingSafeEqual(received, computed);
}

export async function POST(request: Request): Promise<Response> {
  // Read the body as text: re-serialising parsed JSON would change the bytes.
  const rawBody = await request.text();

  if (!isValidSignature(rawBody, request.headers.get('Chargetree-Signature'))) {
    return new Response('Invalid signature', { status: 401 });
  }

  const { events } = JSON.parse(rawBody);

  for (const event of events) {
    // Retries reuse event_id, so this is what stops us acting twice.
    if (await alreadyProcessed(event.event_id)) continue;
    await enqueue(event);
  }

  return new Response('OK', { status: 200 });
}

import hmac
import hashlib
import base64
from flask import Flask, request, abort

app = Flask(__name__)


def is_valid_signature(raw_body: bytes, header: str | None) -> bool:
    """Confirm the delivery was signed with our endpoint's secret."""
    if not header:
        return False

    expected = base64.b64encode(
        hmac.new(SECRET.encode(), raw_body, hashlib.sha256).digest()
    ).decode()

    # compare_digest is constant time, unlike ==
    return hmac.compare_digest(expected, header)


@app.post("/hooks/chargetree")
def chargetree_webhook():
    # request.data is the raw body; request.json would re-serialise it.
    if not is_valid_signature(request.data, request.headers.get("Chargetree-Signature")):
        abort(401)

    for event in request.get_json()["events"]:
        if not already_processed(event["event_id"]):
            enqueue(event)

    return "OK", 200

class ChargetreeWebhooksController < ApplicationController
  skip_before_action :verify_authenticity_token

  def create
    raw_body = request.body.read

    return head :unauthorized unless valid_signature?(raw_body, request.headers['Chargetree-Signature'])

    JSON.parse(raw_body)['events'].each do |event|
      next if already_processed?(event['event_id'])

      enqueue(event)
    end

    head :ok
  end

  private

  # Confirms the delivery was signed with our endpoint's secret.
  def valid_signature?(raw_body, header)
    return false if header.blank?

    expected = Base64.strict_encode64(
      OpenSSL::HMAC.digest('sha256', ENV.fetch('CHARGETREE_WEBHOOK_SECRET'), raw_body)
    )

    ActiveSupport::SecurityUtils.secure_compare(expected, header)
  end
end

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"encoding/json"
	"io"
	"net/http"
	"os"
)

// isValidSignature confirms the delivery was signed with our endpoint's secret.
func isValidSignature(rawBody []byte, header string) bool {
	if header == "" {
		return false
	}

	mac := hmac.New(sha256.New, []byte(os.Getenv("CHARGETREE_WEBHOOK_SECRET")))
	mac.Write(rawBody)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))

	// hmac.Equal is constant time.
	return hmac.Equal([]byte(expected), []byte(header))
}

func handleWebhook(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Bad request", http.StatusBadRequest)
		return
	}

	if !isValidSignature(rawBody, r.Header.Get("Chargetree-Signature")) {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}

	var payload struct {
		Events []map[string]any `json:"events"`
	}
	if err := json.Unmarshal(rawBody, &payload); err != nil {
		http.Error(w, "Bad request", http.StatusBadRequest)
		return
	}

	for _, event := range payload.Events {
		enqueue(event)
	}

	w.WriteHeader(http.StatusOK)
}

async function handleEvent(event: { event_id: string }): Promise<void> {
  // Recording the id first, atomically, means a concurrent redelivery loses the
  // race and exits instead of doing the work a second time.
  const isNew = await markProcessedIfNew(event.event_id);
  if (!isNew) return;

  await doTheWork(event);
}