Postback URLs

ElasticFunnels can fire an outbound HTTP POST to a URL you control whenever a merchant event happens - a purchase, a refund, a subscription renewal, a chargeback, and so on. The payload is the same regardless of which gateway (Stripe, NMI, PayPal, ClickBank, BuyGoods, Digistore24, Klarna, Shop Pay, Shopify Checkout) actually processed the transaction, so you only have to integrate once. This is intentionally simpler than building a full automation graph in the Automations module. Use postback URLs when you just need to forward a clean, predictable JSON event to your own backend, your data warehouse, an internal CRM, or a third-party partner.

Postback URLs do not replace the Automations module - they are complementary. Automations are great for branching logic, retries with conditions, and connecting many third-party services. Postback URLs are great for “fire-and-forget” event forwarding.

Where to configure

In your brand:

Go to Settings → Merchants → pick a merchant → Edit.
Open the Postback URLs tab.
For each event you care about, set:
- Postback URL - https://your-app.example.com/webhooks/elasticfunnels
- Authorization - a token we send as Authorization: Bearer <token>, so you can gate the endpoint at a reverse proxy before it ever reaches your app. Use Generate token for a random one, or paste your own. Leave it blank and we generate one for you when you save - the field is never actually empty, so expect the header on every request.
- Enabled - must be checked for the URL to fire.
Use the Send test button next to each URL to deliver a sample payload right away.
The Recent deliveries section shows status, HTTP code, attempts, the exact payload that was sent, and lets you retry failed deliveries manually.

The same tab also exposes the Signing secret that we use to sign every outbound request. Reveal it once when you wire up your verifier, and you can rotate it at any time.

Supported events

Event key	Fires when
`purchase`	A new approved purchase / order is recorded
`refund`	A refund (full or partial) is recorded
`chargeback`	A chargeback is recorded
`subscription_renewal`	A recurring charge succeeds
`subscription_renewal_failed`	A recurring charge fails (decline, processor error, etc.)
`subscription_cancel`	A subscription is cancelled (by the customer, the merchant, or dunning)
`subscription_change`	A subscription is upgraded / downgraded / paused
`abandon`	Cart abandonment is recorded
`failed_payment`	An initial payment attempt fails (not a renewal - see above)
`shipped`	A tracking number is assigned to an order for the first time

You can configure a different URL per event, or use the same URL for every event - your handler can branch on the event field and on the X-EF-Event header.

Request format

Every request looks like this:

POST /your/handler HTTP/1.1
Host: your-app.example.com
Content-Type: application/json
User-Agent: ElasticFunnels-Postback/1.0
X-EF-Event: purchase
X-EF-Delivery-Id: 01HXYZ...
X-EF-Timestamp: 1755555555
X-EF-Signature: sha256=8c0e...
X-EF-Brand-Id: 42
X-EF-Merchant-Id: 17
Authorization: Bearer <the token on that URL's row>

Header	Purpose
`X-EF-Event`	The event name (same as `event` in the body).
`X-EF-Delivery-Id`	Unique ID for this delivery attempt (use it for idempotency on your side).
`X-EF-Timestamp`	Unix timestamp of when the signature was computed.
`X-EF-Signature`	`sha256=` + HMAC-SHA256 of `<timestamp>.<raw_body>` using your merchant’s signing secret.
`X-EF-Brand-Id`	The brand the merchant belongs to.
`X-EF-Merchant-Id`	The merchant the postback came from.
`Authorization`	Bearer token for that URL’s row. Snapshotted when the delivery is queued, so retries keep sending the token that was in effect at the time - rotating it will not change an already-queued delivery.

Verifying the signature

Reject any request whose recomputed signature does not match X-EF-Signature. Always compare with a constant-time function (hash_equals in PHP, crypto.timingSafeEqual in Node, etc.). It is also a good idea to reject requests whose X-EF-Timestamp is more than a few minutes in the past or future.

$secret    = getenv('EF_POSTBACK_SECRET');
$body      = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_EF_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_EF_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $body, $secret);

if (! hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('invalid signature');
}

if (abs(time() - (int) $timestamp) > 300) {
    http_response_code(401);
    exit('timestamp too old');
}

$payload = json_decode($body, true);

import crypto from 'crypto';

export function verify(req, rawBody, secret) {
  const timestamp = req.headers['x-ef-timestamp'];
  const signature = req.headers['x-ef-signature'];

  const expected =
    'sha256=' +
    crypto
      .createHmac('sha256', secret)
      .update(`${timestamp}.${rawBody}`)
      .digest('hex');

  const ok =
    signature &&
    expected.length === signature.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

  const fresh = Math.abs(Date.now() / 1000 - Number(timestamp)) < 300;

  return ok && fresh;
}

import hmac, hashlib, time

def verify(secret: str, raw_body: bytes, headers: dict) -> bool:
    timestamp = headers.get('x-ef-timestamp', '')
    signature = headers.get('x-ef-signature', '')

    expected = 'sha256=' + hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return False

    return abs(int(time.time()) - int(timestamp)) < 300

Response handling

Return any 2xx status to acknowledge the delivery. The body is ignored (but stored in the deliveries log for debugging - keep it under a few KB).
Any non-2xx response, timeout, or connection error counts as a failure.
Failed deliveries are retried automatically with exponential backoff: 1m → 5m → 30m → 2h → 12h (up to 5 attempts). After the final failure the delivery is marked dead and stops retrying. You can re-queue it manually from the Postback URLs tab.
Each delivery has a unique X-EF-Delivery-Id. Use it to dedupe on your end.

Standardized payload

All events share the same envelope. Fields that don’t apply to a given event are present but null. The full schema:

{
  "event": "purchase",
  "event_id": "ef_evt_01HXYZ...",
  "occurred_at": "2026-04-18T13:45:21+00:00",
  "test": false,

  "brand_id": 42,
  "merchant": {
    "id": 17,
    "gateway": "stripe",
    "name": "Acme Stripe (Live)"
  },

  "order": {
    "order_id": "OFF-1234",
    "public_order_id": "EF-1234",
    "transaction_id": "ch_3PXyz...",
    "conversion_code": "abc123def456",
    "original_conversion_code": null,
    "status": "approved",
    "is_subscription": true,
    "subscription": {
      "cycle_number": 2,
      "status": "active",
      "next_charge_at": "2026-05-18T13:45:21+00:00",
      "retry_count": 0,
      "max_retries": 6,
      "cancel_reason": null,
      "decline_reason": null,
      "recovered_from_dunning": null
    }
  },

  "customer": {
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "name": "Jane Doe",
    "phone": "+15555550100",
    "country": "US",
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "ip": "203.0.113.42"
  },

  "billing": {
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },

  "shipping": {
    "address": "123 Main St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US",
    "tracking_number": null,
    "tracking_url": null,
    "carrier": null,
    "shipping_method": null
  },

  "amounts": {
    "currency": "USD",
    "total": 49.0,
    "subtotal": 45.0,
    "taxes": 4.0,
    "shipping": 0.0,
    "discount": 0.0,
    "cogs": 12.0,
    "merchant_commission": 0.0,
    "affiliate_commission": 0.0,
    "refunded_total": 0.0
  },

  "products": [
    {
      "code": "SKU-MAIN-1",
      "sku": "SKU-MAIN-1",
      "product_id": 901,
      "name": "Acme Widget",
      "quantity": 1,
      "price": 45.0,
      "unit_price": 45.0,
      "total": 45.0,
      "currency": "USD",
      "type": "main",
      "is_bonus": false,
      "image_url": null,
      "tracking_number": null,
      "tracking_url": null,
      "carrier": null
    }
  ],

  "tracking": {
    "click_code": "ck_abc123",
    "session_id": "sess_xyz",
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "spring",
    "utm_term": null,
    "utm_content": null,
    "gclid": null,
    "fbclid": null,
    "subid": null,
    "subid2": null,
    "subid3": null,
    "subid4": null,
    "subid5": null,
    "vtid": null
  },

  "affiliate": {
    "id": null,
    "source": null,
    "merchant_affiliate_id": null,
    "merchant_affiliate_name": null
  },

  "funnel": {
    "funnel_id": 7,
    "page_id": 21,
    "domain_id": 3
  },

  "coupon": {
    "code": null,
    "discount": 0.0
  },

  "meta": {
    "payment_method": "card",
    "payment_status": "completed",
    "last4": "4242",
    "gateway": "stripe"
  }
}

Passing your own tracking values

Six fields in tracking are yours to populate - vtid and subid through subid5. Put any of them on the landing URL or on the buy link as a query parameter and we capture, store, and echo the value back on every postback for that order:

https://yourdomain.com/lander?vtid=YOUR_KEY
https://yourdomain.com/b?p=product_1&vtid=YOUR_KEY

vtid - “vendor tracking ID”. A single general-purpose slot, independent of gateway and of any affiliate network. Best choice for a third-party tracker or session key that you need reflected back. Keep values under 512 characters: the postback echoes the value in full, but the click record truncates at 512, so a longer value will not match between the two when you reconcile. This matters most for base64/encoded composite keys, which get long quickly.
subid .. subid5 - five slots conventionally used for affiliate-network sub-tracking (RedTrack, Voluum, and similar).

All six are also filterable and exportable from the Conversions report, so you can reconcile against the postbacks you received.

Upsell and rebill conversions inherit these values from the original purchase, so a subscription’s renewals carry the same vtid as the sale that created it.

Event-specific notes

refund / chargeback - amounts.total is negative for the refunded portion, and order.original_conversion_code references the original purchase row.
subscription_renewal_failed - order.subscription.retry_count and order.subscription.next_charge_at reflect the dunning schedule, and meta.payment_status will typically be failed with a populated order.subscription.decline_reason.
subscription_cancel - order.subscription.status is cancelled and order.subscription.cancel_reason is filled when available.
shipped - fires the first time a tracking number is set on an order. shipping.tracking_number, shipping.tracking_url, and shipping.carrier are populated. We dedupe per order so you only get one shipped event.
abandon - order.status is abandoned and customer may be partially populated depending on how far the visitor got in checkout.
test - Postbacks fired from the Send test button or originating from a sandbox merchant set test: true. Use it to gate side effects in your handler.

Example: minimal Express.js handler

import express from 'express';
import crypto from 'crypto';

const app = express();
const SECRET = process.env.EF_POSTBACK_SECRET;

app.post(
  '/webhooks/elasticfunnels',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const raw = req.body.toString('utf8');
    const ts = req.header('x-ef-timestamp') || '';
    const sig = req.header('x-ef-signature') || '';

    const expected =
      'sha256=' + crypto.createHmac('sha256', SECRET).update(`${ts}.${raw}`).digest('hex');

    const valid =
      sig.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)) &&
      Math.abs(Date.now() / 1000 - Number(ts)) < 300;

    if (!valid) return res.status(401).end();

    const evt = JSON.parse(raw);
    console.log(`[${evt.event}] order=${evt.order.public_order_id} total=${evt.amounts.total}`);

    res.status(200).end();
  }
);

app.listen(3000);

Operational details

Deliveries are processed asynchronously so they do not block the gateway request that triggered them.
Failed deliveries are retried automatically after the configured backoff window has elapsed.
The Postback URLs tab shows recent deliveries, including the URL, payload, headers, response body, attempts, and final status.
The signing secret is stored encrypted at rest. Rotating it invalidates all previous signatures immediately - only do it if you can update your verifier in lockstep.

Get Started

Essentials

Analytics & Metrics

Funnels

Page Events

Pages

Merchants

Affiliates

Integrations

Members Area

Forms & Data

Subscriptions

Emails

Products & Sales

Domains & Customization

Development & Debugging

Frontend Template Engine

Backend Template Engine

CRM

Backend Scripts

Where to configure

Supported events

Request format

Verifying the signature

Response handling

Standardized payload

Passing your own tracking values

Event-specific notes

Example: minimal Express.js handler

Operational details

​Where to configure

​Supported events

​Request format

​Verifying the signature

​Response handling

​Standardized payload

​Passing your own tracking values

​Event-specific notes

​Example: minimal Express.js handler

​Operational details

Where to configure

Supported events

Request format

Verifying the signature

Response handling

Standardized payload

Passing your own tracking values

Event-specific notes

Example: minimal Express.js handler

Operational details