Webhooks

CatalystPay's outbound webhook system notifies your server when events occur -- payments complete, transactions settle, chargebacks arrive, subscriptions change. This guide covers event types, delivery mechanics, signature verification, and best practices.

Event types

Webhook headers

Every webhook delivery includes these headers:

Delivery methods

Each webhook endpoint supports one of two delivery methods:

Both methods include the same HMAC signature and event type headers.

Signature verification

All webhook deliveries are signed with HMAC-SHA256 using a per-profile signing secret. Verify the signature before processing any webhook data.

How the signature is computed

1. Serialize the JSON payload with sorted keys and compact separators: json.dumps(payload, sort_keys=True, separators=(',', ':'))
2. Compute HMAC-SHA256 using the webhook profile's signing secret as the key
3. The result is a lowercase hex digest in the X-CatalystPay-Signature header

Verification code

import hmac
import hashlib
import json

def verify_webhook(payload_body: bytes, signature: str, signing_secret: str) -> bool:
    # Reconstruct canonical JSON (sorted keys, compact separators)
    payload_dict = json.loads(payload_body)
    canonical = json.dumps(payload_dict, sort_keys=True, separators=(",", ":"))

    expected = hmac.new(
        signing_secret.encode("utf-8"),
        canonical.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(expected, signature)

# Usage in a Flask/Django view:
signature = request.headers.get("X-CatalystPay-Signature", "")
if not verify_webhook(request.body, signature, SIGNING_SECRET):
    return HttpResponse(status=401)

const crypto = require("crypto");

// Recursively sort object keys to match Python's sort_keys=True
function sortKeys(obj) {
  if (typeof obj !== "object" || obj === null) return obj;
  if (Array.isArray(obj)) return obj.map(sortKeys);
  return Object.keys(obj).sort().reduce((acc, key) => {
    acc[key] = sortKeys(obj[key]);
    return acc;
  }, {});
}

function verifyWebhook(payloadBody, signature, signingSecret) {
  const payload = JSON.parse(payloadBody);
  // Compact JSON with sorted keys -- matches Python's
  // json.dumps(payload, sort_keys=True, separators=(',', ':'))
  const canonical = JSON.stringify(sortKeys(payload));

  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(canonical)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

# Compute the expected signature manually:
echo -n '{"amount":"29.99","currency":"EUR","email":"[email protected]","order_number":"ORD-a1b2c3d4","session_token":"ps_...","status":"COMPLETED"}' \
  | openssl dgst -sha256 -hmac "your_signing_secret"

Retry policy

Failed deliveries are retried with exponential backoff:

Maximum retries: 5. After all retries are exhausted, the delivery is marked as FAILED.

What gets retried

• HTTP 5xx responses -- Server errors are retried
• HTTP 429 -- Rate limit responses are retried
• Network errors -- Connection timeouts, DNS failures

What does NOT get retried

• HTTP 4xx (except 429) -- Client errors like 400, 401, 403, 404 are treated as permanent failures. Retrying the same request will produce the same error.

Circuit breaker

Each webhook endpoint tracks consecutive failures. After 20 consecutive failures, CatalystPay automatically deactivates the endpoint.

A successful delivery (HTTP 2xx) resets the failure counter to zero. Intermittent failures do not trigger the circuit breaker -- only sustained failure.

When the circuit breaker trips, an administrator must manually reactivate the endpoint after investigating the root cause.

Endpoint requirements

Your webhook endpoint must:

• Respond within 15 seconds (request timeout)
• Return an HTTP 2xx status code to indicate successful receipt
• Be publicly accessible over HTTPS

Idempotency

Webhooks operate under an at-least-once delivery guarantee. The same event may be delivered multiple times due to network timeouts, worker restarts, or retry behavior.

Design your webhook handlers to be idempotent. Use the entity identifiers in the payload (order.id, transaction.id, subscription.id) as idempotency keys. If you have already processed an event for that entity and event type, skip the duplicate.

Payload variables

Payloads are built from a configurable mapping. Each endpoint defines which variables to include. Common payload variables per event type:

payment_session.completed

transaction.status_changed

Endpoints can filter on specific status values via a status_filter list, so you only receive webhooks for statuses you care about (e.g., only approved transactions).

chargeback.created

Event routing

Webhooks are organized around a profile/endpoint hierarchy:

flowchart TB
    C[Campaign] -->|M2M| WP[Webhook Profile]
    WP -->|1:N| E1[Endpoint: order.created]
    WP -->|1:N| E2[Endpoint: transaction.status_changed]
    WP -->|1:N| E3[Endpoint: chargeback.created]
    E2 -->|optional| SF[Status Filter: approved, declined]

A Webhook Profile groups endpoints and carries the signing secret. Profiles are linked to campaigns via a many-to-many relationship, so the same profile can serve multiple campaigns.

A Webhook Endpoint listens for a specific event type and delivers to a specific URL.

For Direct Mode sessions (no campaign), webhook routing uses the webhook_profile_id explicitly attached to the Order.

Priority queues

This separation ensures that a large CSV import does not delay delivery of real-time payment notifications.

Best practices

1. Always verify signatures before processing webhook data
2. Return 200 immediately, then process asynchronously
3. Implement idempotency using entity IDs as dedup keys
4. Use the webhook as the authoritative signal for order fulfillment, not the /pay/ response
5. Monitor your endpoint -- 20 consecutive failures will trigger the circuit breaker
6. Use webhook.site for testing before deploying your production endpoint

Next steps

• HPP Integration -- See webhooks in context of a full integration
• Sandbox Testing -- Test webhook delivery and signature verification
• Reconciliation -- Pull data programmatically as an alternative to webhooks