Webhooks

Listen to events on your SubscriptionFlow account so your integration can automatically trigger reactions.

SubscriptionFlow uses webhooks to notify your application in real time when something happens -- a subscription is renewed, an invoice is paid, a payment method expires, and more. Instead of polling the API, you receive an HTTP POST request at a URL you choose.

How webhooks work

1. An event occurs in your SubscriptionFlow account (e.g., a customer's subscription renews).
2. SubscriptionFlow creates a webhook payload containing the event type and the full or custom entity data.
3. SubscriptionFlow sends an HTTP request to each webhook endpoint registered for that event.
4. Your server receives the request, processes it, and returns a 2xx status code to acknowledge receipt.

Quickstart

Follow these steps to start receiving webhooks in under 5 minutes.

Step 1: Create your endpoint

Build an HTTP endpoint on your server that can receive POST requests. SubscriptionFlow sends webhook data as application/x-www-form-urlencoded form parameters.

const express = require("express");
const app = express();

app.use(express.urlencoded({ extended: true }));

app.post("/webhooks/subscriptionflow", (req, res) => {
  const event = req.body.event;
  const method = req.body.method;

  // Route to the appropriate handler based on event type
  switch (event) {
    case "renewed":
      handleSubscriptionRenewal(req.body);
      break;
    case "paid":
      handleInvoicePaid(req.body);
      break;
    case "failed":
      handleTransactionFailed(req.body);
      break;
    default:
      console.log(`Unhandled event type: ${event}`);
  }

  // Acknowledge receipt immediately
  res.status(200).send("OK");
});

app.listen(4242, () => console.log("Webhook server running on port 4242"));

<?php

// Read the incoming webhook data
$event  = $_POST['event'] ?? null;
$method = $_POST['method'] ?? null;

// Route to the appropriate handler
switch ($event) {
    case 'renewed':
        handleSubscriptionRenewal($_POST);
        break;
    case 'paid':
        handleInvoicePaid($_POST);
        break;
    case 'failed':
        handleTransactionFailed($_POST);
        break;
    default:
        error_log("Unhandled event type: " . $event);
}

// Acknowledge receipt
http_response_code(200);
echo 'OK';

from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/subscriptionflow", methods=["POST"])
def webhook():
    event = request.form.get("event")

    if event == "renewed":
        handle_subscription_renewal(request.form)
    elif event == "paid":
        handle_invoice_paid(request.form)
    elif event == "failed":
        handle_transaction_failed(request.form)
    else:
        print(f"Unhandled event type: {event}")

    return "OK", 200

Tip: Your endpoint should return a 2xx response as quickly as possible. Move any heavy processing to a background job or queue to avoid timeouts.

Step 2: Register the webhook in SubscriptionFlow

1. Go to Settings > Webhooks in your SubscriptionFlow dashboard.
2. Click Create Webhook.
3. Configure the webhook:

4. Click Save.

Important: Webhook URLs must use HTTPS with a valid SSL certificate. HTTP endpoints are not accepted.

Step 3: Test your webhook

To verify your endpoint is working:

1. Create a test subscription or trigger the relevant action in your SubscriptionFlow account.
2. Check your webhook logs at Settings > Webhooks > Logs to confirm delivery.
3. Verify your server received and processed the request.

You can also use tools like webhook.site to inspect the raw payload before pointing the webhook at your production server.

Events

Every webhook request includes an event field that tells you what happened. Events are grouped by module.

Subscription events

Invoice events

Transaction events

Payment method events

Email events

Payload format

Every webhook request contains the event data. The shape of the payload depends on the payload type you select when creating the webhook.

Default payload

The default payload sends the full entity representation -- the same data you'd get from the corresponding REST API endpoint.

Example: subscription.renewed

{
  "type": "subscription",
  "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "attributes": {
    "name": "SUB-00142",
    "display_name": "Pro Monthly - John Doe",
    "status": "active",
    "type": "auto_recurring",
    "total_amount": "49.99",
    "next_bill_date": "2026-05-01",
    "billing_end_date": null,
    "is_auto_renew": true,
    "renewal_type": "auto",
    "renewal_period": "1",
    "renewal_period_type": "month",
    "renewed_at": "2026-04-01",
    "trial_period": null,
    "trial_expiry": null,
    "subscription_mrr": "49.99",
    "payment_status": "paid",
    "tags": ["premium", "annual-promo"],
    "created_at": "2025-01-15T10:30:00.000000Z",
    "updated_at": "2026-04-01T00:00:12.000000Z"
  },
  "relationships": {
    "customer_id": {
      "type": "customer",
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "attributes": {
        "first_name": "John",
        "last_name": "Doe",
        "primary_email": "john.doe@example.com"
      }
    }
  },
  "event": "renewed",
  "method": "POST"
}

Example: invoice.paid

{
  "type": "invoice",
  "id": "2b3c4d5e-6f7a-8b9c-0d1e-2f3a4b5c6d7e",
  "attributes": {
    "name": "INV-00318",
    "status": "paid",
    "invoice_date": "2026-04-01",
    "due_date": "2026-04-15",
    "currency": "USD",
    "sub_total": "49.99",
    "tax_amount": "4.50",
    "total_amount": "54.49",
    "outstanding_amount": "0.00",
    "received_payment": "54.49",
    "description": "Pro Monthly subscription renewal",
    "created_at": "2026-04-01T00:00:12.000000Z",
    "updated_at": "2026-04-01T00:01:05.000000Z"
  },
  "relationships": {
    "customer_id": {
      "type": "customer",
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "attributes": {
        "first_name": "John",
        "last_name": "Doe",
        "primary_email": "john.doe@example.com"
      }
    }
  },
  "event": "paid",
  "method": "POST"
}

Example: transaction.failed

{
  "type": "transaction",
  "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "attributes": {
    "name": "TXN-00587",
    "number": "587",
    "status": "failed",
    "amount": "54.49",
    "currency": "USD",
    "date": "2026-04-01",
    "type": "charge",
    "decline_reason": "insufficient_funds",
    "reason_code": "card_declined",
    "created_at": "2026-04-01T00:01:00.000000Z",
    "updated_at": "2026-04-01T00:01:00.000000Z"
  },
  "relationships": {
    "customer_id": {
      "type": "customer",
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "attributes": {
        "first_name": "John",
        "last_name": "Doe",
        "primary_email": "john.doe@example.com"
      }
    }
  },
  "event": "failed",
  "method": "POST"
}

Example: paymentmethod.expired

{
  "type": "paymentmethod",
  "id": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
  "attributes": {
    "name": "Visa ending 4242",
    "status": "expired",
    "payment_method_type": "credit_card",
    "payment_method_subtype": "visa",
    "last_four_digits": "4242",
    "expiry_month": "03",
    "expiry_year": "2026",
    "gateway_name": "Stripe",
    "default": true,
    "first_name": "John",
    "last_name": "Doe",
    "billing_email": "john.doe@example.com",
    "created_at": "2025-01-15T10:32:00.000000Z",
    "updated_at": "2026-04-01T00:00:00.000000Z"
  },
  "relationships": {
    "parent_id": {
      "type": "customer",
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
    }
  },
  "event": "expired",
  "method": "POST"
}

Custom payload

Custom payloads let you control exactly which fields are sent. You map fields using the template syntax {{ModelName_fieldname}} and add any static key-value pairs you need.

Configuration example:

Resulting payload:

{
  "sub_id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "email": "john.doe@example.com",
  "plan": "Pro Monthly",
  "status": "active",
  "source": "subscriptionflow",
  "event": "renewed",
  "method": "POST"
}

Custom payloads also support the GET method. When using GET, data is sent as query string parameters instead of a POST body.

Delivery details

Retry behavior

Fields included in every request

Regardless of payload type, every webhook request includes:

Full field reference

These are all fields available in the DEFAULT payload for each module.

Webhook logs

Enable logging from Settings > Webhooks to record all delivery attempts. Each log entry includes:

Use logs to debug failed deliveries, inspect payloads, and confirm your endpoint is processing events correctly.

Best practices

Return a 2xx quickly. Your endpoint should acknowledge receipt within 30 seconds. Offload any heavy processing to a background job.

Handle duplicate deliveries. In rare cases, the same event may be sent more than once. Use the entity id and event to deduplicate on your end.

Keep your SSL certificate valid. SubscriptionFlow requires HTTPS. If your certificate expires, webhook delivery will fail.

Use DEFAULT payloads for complete data. The DEFAULT payload mirrors the API response and includes all fields and relationships. Use CUSTOM payloads only when you need to match a specific external format or limit the data sent.

Monitor your logs. Enable webhook logging and review it regularly to catch delivery failures before they impact your integration.

Don't rely on delivery order. Webhooks may arrive out of order. Use timestamps like updated_at to determine the latest state of an entity.