Payeny-Signature: t=<unix>,v1=<hmac>
Webhooks & Cryptographic Signatures
Payeny dispatches real-time signed HTTP POST webhooks to each merchant's configured webhook URL whenever a checkout session completes, a subscription changes state, an invoice is paid or fails, or a refund is issued.
success_url alone to provision paid entitlements. Always verify the Payeny-Signature header on incoming webhooks before fulfilling orders or activating subscriptions.
Standard Outbound Webhook Envelope
Every outbound webhook delivered to your merchant endpoint shares a deterministic top-level JSON envelope containing id, type, created (Unix timestamp), livemode: false, merchant (your tenant slug, e.g. acme), and data.object:
{
"id": "evt_70f4e47c3a6801cb6c11",
"object": "event",
"type": "checkout.completed",
"created": 1792720840,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"session_id": "cs_27b5028e3d12ebed8b0e04ce",
"order_reference": "ORD-261022-C05D2",
"amount_cents": 5000,
"amount_total": 5000,
"currency": "usd",
"payment_intent": "pi_3UTXmcAlRoAmlooY1rpSrm2Y",
"payment_id": "pay_80a9228f78ee2a277a56",
"client_reference_id": "client_ref_12345",
"status": "succeeded"
}
}
}
event.id (format ^evt_[0-9a-f]{20}$) in your local database. If an event ID has already been processed, return HTTP 200 OK immediately without re-executing order fulfillment.
Outbound Event Catalog
Payeny emits the following canonical event types across all merchant workspaces:
| Event Type | Resource | When Emitted |
|---|---|---|
| checkout.completed | cs_... |
Customer completes payment or subscription signup on hosted checkout (or Stripe checkout.session.completed). |
| checkout.session.completed | cs_... |
Embedded or custom checkout session is completed and order fulfilled. |
| payment.created | pay_... |
A new direct payment or charge attempt is initiated via API. |
| payment.succeeded | pay_... |
Direct payment or checkout payment is successfully settled and confirmed. |
| payment.captured | pay_... |
An authorized payment is captured. |
| payment.canceled | pay_... |
An uncaptured payment or authorization is canceled. |
| payment.failed | pay_... |
A payment intent or card authorization attempt fails. |
| refund.created | ref_... |
Full or partial refund is issued via API, admin dashboard, or Stripe sync. |
| subscription.created | sub_... |
A new recurring subscription is created via API, hosted checkout, or sync. |
| subscription.updated | sub_... |
Subscription plan changes, cancellation is scheduled, subscription is resumed, or status updates. |
| subscription.canceled | sub_... |
Subscription is canceled immediately or reaches the end of its billing cycle. |
| subscription.renewed | sub_... |
Subscription successfully renews for a subsequent billing period. |
| subscription.payment_failed | sub_... |
Recurring subscription billing cycle charge attempt fails. |
| invoice.created | in_... |
A new customer billing invoice is generated. |
| invoice.paid | in_... |
Initial or recurring subscription invoice payment succeeds. |
| invoice.payment_failed | in_... |
Invoice charge attempt fails (e.g. card declined or insufficient funds). |
| dispute.created | dp_... |
Customer files a payment dispute or chargeback with issuing bank. |
| dispute.closed | dp_... |
Dispute inquiry is resolved, won, or lost. |
| payout.status | po_... |
Payout transfer to seller external bank account updates status (paid, failed, pending). |
| transaction.agreed | txn_... |
Both buyer and seller complete mutual agreement on a marketplace transaction. |
| merchant.created | mer_... |
A new connected merchant workspace is created. |
| merchant.updated | mer_... |
Connected merchant profile, status, or payout capability updates. |
| portal.session.created | pts_... |
Customer billing management portal session is created. |
| portal.session.accessed | pts_... |
Customer accesses their self-service billing portal session. |
| usage.recorded | usg_... |
Metered usage event is recorded for a subscription customer. |
| usage.invoiced | usg_... |
Aggregated metered usage is finalized and invoiced. |
Event Payload Examples
payment.succeeded{
"id": "evt_10a1b2c3d4e5f6a7b8c9",
"object": "event",
"type": "payment.succeeded",
"created": 1792667800,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "pay_9876543210abcdef1234",
"amount": 2900,
"amount_cents": 2900,
"currency": "usd",
"status": "succeeded",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"payment_method": "pm_card_visa",
"client_reference_id": "order_ref_12345",
"fee_cents": 25,
"net_cents": 2875,
"description": "Standard Plan Subscription"
}
},
"api_version": "2026-09-01"
}
payment.failed{
"id": "evt_20b2c3d4e5f6a7b8c9d0",
"object": "event",
"type": "payment.failed",
"created": 1792667820,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "pay_failed_456789abcdef0123",
"amount_cents": 2900,
"currency": "usd",
"status": "failed",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"error_code": "card_declined",
"decline_code": "insufficient_funds",
"error_message": "Your card has insufficient funds."
}
},
"api_version": "2026-09-01"
}
refund.created{
"id": "evt_99887766554433221100",
"object": "event",
"type": "refund.created",
"created": 1792668100,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "ref_5566778899aabbccddee",
"payment_id": "pay_1234567890abcdef",
"amount_cents": 1500,
"currency": "usd",
"reason": "requested_by_customer",
"status": "succeeded"
}
},
"api_version": "2026-09-01"
}
subscription.created{
"id": "evt_30c3d4e5f6a7b8c9d0e1",
"object": "event",
"type": "subscription.created",
"created": 1792668200,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "sub_11223344556677889900",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"price_id": "price_1a2b3c4d5e6f7a8b9c0d1e2f",
"plan_name": "Studio Pro Plan",
"status": "active",
"cancel_at_period_end": false,
"amount_cents": 2900,
"currency": "usd",
"interval": "month",
"current_period_start": "2026-10-22 10:00:00",
"current_period_end": "2026-11-22 10:00:00"
}
},
"api_version": "2026-09-01"
}
subscription.updated{
"id": "evt_11223344556677889900",
"object": "event",
"type": "subscription.updated",
"created": 1792667850,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "sub_9876543210abcdef1234",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"price_id": "price_1a2b3c4d5e6f7a8b9c0d1e2f",
"plan_name": "Studio Pro Plan",
"status": "active",
"cancel_at_period_end": false,
"amount_cents": 2900,
"amount_total": 2900,
"currency": "usd",
"interval": "month",
"proration_behavior": "create_prorations",
"current_period_start": "2026-10-22 10:00:00",
"current_period_end": "2026-11-22 10:00:00"
}
},
"api_version": "2026-09-01"
}
subscription.canceled{
"id": "evt_40d4e5f6a7b8c9d0e1f2",
"object": "event",
"type": "subscription.canceled",
"created": 1792668300,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "sub_9876543210abcdef1234",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"status": "canceled",
"cancel_at_period_end": false,
"canceled_at": "2026-10-22 10:30:00",
"amount_cents": 2900,
"currency": "usd"
}
},
"api_version": "2026-09-01"
}
invoice.paid{
"id": "evt_ccddeeff001122334455",
"object": "event",
"type": "invoice.paid",
"created": 1792667910,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "in_1042",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"subscription_id": "sub_9876543210abcdef1234",
"amount_paid": 2900,
"amount_due": 0,
"currency": "usd",
"status": "paid",
"hosted_invoice_url": "https://payeny.com/invoices/inv_tok_1042",
"invoice_pdf": "https://payeny.com/api/v1/invoices/1042/pdf"
}
},
"api_version": "2026-09-01"
}
invoice.payment_failed{
"id": "evt_ffeeddccbbaa00998877",
"object": "event",
"type": "invoice.payment_failed",
"created": 1792667920,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "in_1043",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"subscription_id": "sub_9876543210abcdef1234",
"amount_due": 2900,
"amount_paid": 0,
"currency": "usd",
"status": "open",
"attempt_count": 1,
"hosted_invoice_url": "https://payeny.com/invoices/inv_tok_1043"
}
},
"api_version": "2026-09-01"
}
checkout.completed{
"id": "evt_aabb1122334455667788",
"object": "event",
"type": "checkout.completed",
"created": 1792667930,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "cs_27b5028e3d12ebed8b0e04ce",
"session_id": "cs_27b5028e3d12ebed8b0e04ce",
"order_reference": "ORD-261022-C05D2",
"amount_total": 5000,
"currency": "usd",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"status": "complete"
}
},
"api_version": "2026-09-01"
}
payment.created{
"id": "evt_9900aabbccddeeff1122",
"object": "event",
"type": "payment.created",
"created": 1792667940,
"livemode": false,
"merchant": "acme",
"data": {
"object": {
"id": "pay_9876543210abcdef1234",
"amount_cents": 2900,
"currency": "usd",
"status": "pending",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c"
}
},
"api_version": "2026-09-01"
}
checkout.session.completed with "mode": "setup")Sent when a customer saves a card through a setup session (hosted page, Elements, or reconciled from the processor's setup_intent.succeeded). Nothing is charged. The saved card is in payment_method and, flattened, in payment_method_id and card (brand, last4, exp_month, exp_year). subscriptions_updated lists subscriptions now using the card; subscriptions_skipped lists any that were not updated, each with a reason. Full card numbers and CVCs are never sent.
{
"id": "evt_20b1c2d3e4f5a6b7c8d9",
"object": "event",
"type": "checkout.session.completed",
"livemode": false,
"data": {
"object": {
"id": "cs_fc8e0e7f4531d237cb0b847d",
"object": "checkout.session",
"mode": "setup",
"status": "completed",
"customer_id": "cus_9f8e7d6c5b4a3f2e1d0c",
"subscription_id": "sub_1a2b3c4d5e6f7a8b9c0d",
"setup_intent_id": "seti_1Example",
"setup_intent_status": "succeeded",
"payment_method": { "id": "pm_1Example", "brand": "Visa", "last4": "4242", "exp_month": 12, "exp_year": 2030 },
"payment_method_id": "pm_1Example",
"card": { "brand": "Visa", "last4": "4242", "exp_month": 12, "exp_year": 2030 },
"subscriptions_updated": ["sub_1a2b3c4d5e6f7a8b9c0d"],
"subscriptions_skipped": [],
"amount_charged_cents": 0,
"livemode": false
}
}
}
Signature Verification (Payeny-Signature)
Payeny signs every outbound webhook payload using your merchant's webhook secret (whsec_...) and includes the signature in the Payeny-Signature HTTP header:
Payeny-Signature: t=1792667700,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
- Split the
Payeny-Signatureheader on,to extract the Unix timestamptand the hex HMAC digestv1. - Construct the signed payload string by concatenating
t, a literal period., and the exact raw UTF-8 HTTP request body:"<t>.<raw body>". - Compute the lower-case hex
HMAC-SHA256of"<t>.<raw body>"using your merchant'swhsec_...secret as the key. - Replay Protection: Reject any webhook where
abs(current_time - t) > 300(5 minutes). This prevents replay attacks where a third party captures and retransmits valid payloads. - Constant-Time Comparison: Compare your computed digest to
v1using a timing-safe comparison function (hash_equalsin PHP,crypto.timingSafeEqualin Node.js, orhmac.compare_digestin Python) to prevent byte-by-byte timing attacks.
PHP Signature Verification Example
<?php
$rawBody = file_get_contents('php://input');
$sigHeader = $_SERVER['HTTP_PAYENY_SIGNATURE'] ?? '';
$webhookSecret = getenv('PAYENY_WEBHOOK_SECRET'); // e.g. whsec_acme_...
function verifyPayenyWebhook(string $rawBody, string $sigHeader, string $secret, int $tolerance = 300): array
{
$parts = [];
foreach (explode(',', $sigHeader) as $segment) {
[$k, $v] = array_pad(explode('=', trim($segment), 2), 2, '');
$parts[$k] = $v;
}
$timestamp = (int)($parts['t'] ?? 0);
$v1 = $parts['v1'] ?? '';
if ($timestamp <= 0 || $v1 === '') {
http_response_code(400);
throw new RuntimeException('Missing timestamp or v1 signature in Payeny-Signature header.');
}
if (abs(time() - $timestamp) > $tolerance) {
http_response_code(400);
throw new RuntimeException('Webhook timestamp outside tolerance window.');
}
$signedPayload = $timestamp . '.' . $rawBody;
$expectedSignature = hash_hmac('sha256', $signedPayload, $secret);
if (!hash_equals($expectedSignature, $v1)) {
http_response_code(400);
throw new RuntimeException('Invalid Payeny-Signature HMAC digest.');
}
return json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
}
$event = verifyPayenyWebhook($rawBody, $sigHeader, $webhookSecret);
// Handle $event['type'] ('checkout.completed', 'subscription.created', etc.)
http_response_code(200);
echo json_encode(['received' => true]);
JavaScript / Node.js Signature Verification Example
import crypto from 'node:crypto';
import express from 'express';
const app = express();
export function verifyPayenySignature(rawBody, sigHeader, webhookSecret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
String(sigHeader || '')
.split(',')
.map((item) => item.trim().split('='))
);
const timestamp = Number(parts.t);
const signature = parts.v1 || '';
if (!timestamp || !signature) {
throw new Error('Malformed Payeny-Signature header');
}
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - timestamp) > toleranceSeconds) {
throw new Error('Webhook timestamp outside tolerance window');
}
const signedPayload = `${timestamp}.${rawBody}`;
const expected = crypto
.createHmac('sha256', webhookSecret)
.update(signedPayload, 'utf8')
.digest('hex');
const expectedBuf = Buffer.from(expected, 'hex');
const receivedBuf = Buffer.from(signature, 'hex');
if (
expectedBuf.length !== receivedBuf.length ||
!crypto.timingSafeEqual(expectedBuf, receivedBuf)
) {
throw new Error('Payeny-Signature verification failed');
}
return JSON.parse(rawBody);
}
app.post('/webhooks/payeny', express.raw({ type: 'application/json' }), (req, res) => {
try {
const rawBody = req.body.toString('utf8');
const sigHeader = req.headers['payeny-signature'];
const event = verifyPayenySignature(rawBody, sigHeader, process.env.PAYENY_WEBHOOK_SECRET);
// Handle event.type ('checkout.completed', 'subscription.updated', etc.)
res.status(200).json({ received: true, id: event.id });
} catch (err) {
res.status(400).json({ error: err.message });
}
});
Python Signature Verification Example
import hmac
import hashlib
import time
import json
from flask import Flask, request, jsonify
app = Flask(__name__)
def verify_payeny_signature(raw_body: str, sig_header: str, webhook_secret: str, tolerance_seconds: int = 300) -> dict:
parts = {}
for segment in (sig_header or "").split(","):
if "=" in segment:
k, v = segment.strip().split("=", 1)
parts[k] = v
timestamp = int(parts.get("t", 0))
signature = parts.get("v1", "")
if not timestamp or not signature:
raise ValueError("Malformed Payeny-Signature header: missing timestamp or v1 signature.")
now = int(time.time())
if abs(now - timestamp) > tolerance_seconds:
raise ValueError(f"Webhook timestamp outside tolerance window ({abs(now - timestamp)}s > {tolerance_seconds}s).")
signed_payload = f"{timestamp}.{raw_body}".encode("utf-8")
expected_sig = hmac.new(webhook_secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
# Timing-safe comparison to prevent byte-by-byte timing attacks
if not hmac.compare_digest(expected_sig, signature):
raise ValueError("Invalid Payeny-Signature HMAC digest.")
return json.loads(raw_body)
@app.route("/webhooks/payeny", methods=["POST"])
def payeny_webhook():
raw_body = request.get_data(as_text=True)
sig_header = request.headers.get("Payeny-Signature", "")
secret = "whsec_..." # Loaded securely from environment
try:
event = verify_payeny_signature(raw_body, sig_header, secret)
# Handle event["type"] ('checkout.completed', 'subscription.updated', etc.)
return jsonify({"received": True, "id": event.get("id")}), 200
except ValueError as e:
return jsonify({"error": str(e)}), 400
Retry Policy, Exponential Backoff & Delivery Logs
Payeny expects your webhook endpoint to return an HTTP 2xx status code within 10 seconds. Any non-2xx response (such as 4xx or 5xx) or any network timeout exceeding 10 seconds is logged and scheduled for automatic retry with exponential backoff:
| Attempt | Backoff Delay | Status After Failure |
|---|---|---|
| Initial Delivery (Attempt 1) | Immediate (0s) | retrying (schedules Retry 1) |
| Retry 1 (Attempt 2) | +1 minute (60s) | retrying (schedules Retry 2) |
| Retry 2 (Attempt 3) | +5 minutes (300s) | retrying (schedules Retry 3) |
| Retry 3 (Attempt 4) | +30 minutes (1,800s) | retrying (schedules Retry 4) |
| Retry 4 (Attempt 5) | +2 hours (7,200s) | retrying (schedules Retry 5) |
| Retry 5 (Attempt 6) | +12 hours (43,200s) | retrying (schedules Retry 6) |
| Retry 6 (Attempt 7) | +24 hours (86,400s) | Marked failed permanently |
Delivery Log & Manual Resend: Every delivery attempt records the event ID, target URL, attempt number, HTTP status code, response snippet, and duration in milliseconds. Operators can inspect all deliveries and trigger a manual Resend from the Payeny Admin dashboard (/admin/merchants and /admin/webhooks).
Webhook Endpoints & Allowed Redirect Domains API
Merchant ScopedMerchants can dynamically register HTTPS webhook receiver endpoints and allowlisted redirect hostnames for checkout redirection:
GET /api/v1/webhook_endpoints— List configured webhook endpoints for the calling merchant.POST /api/v1/webhook_endpoints— Register an HTTPS webhook URL. Returns thewhsec_...signature secret once only on creation.DELETE /api/v1/webhook_endpoints/{id}— Remove an endpoint.GET /api/v1/allowed_redirect_domains— List allowlisted redirect hostnames.POST /api/v1/allowed_redirect_domains— Allowlist a bare domain (e.g.example.com) or explicit wildcard (*.example.com).DELETE /api/v1/allowed_redirect_domains/{id}— Delete an allowed domain.POST /api/v1/events/{id}/resend— Admin / merchant resend action that re-delivers an event with the same event ID, fresh timestamp signature, logs the attempt in delivery logs, and never duplicates ledger rows.POST /api/v1/events/{id}/replay— Test-mode-only replay helper supportingmode: "single" | "duplicate" | "out_of_order"and optionalunsigned: true(refused in live mode with HTTP403 test_mode_only).
curl -X POST https://payeny.com/api/v1/webhook_endpoints \
-H "Authorization: Bearer sec_test_acme_xxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/webhooks/payeny", "description": "Production Webhook"}'
Test-Mode Webhook Replay & Unsigned Webhook Verification
POST /api/v1/events/{id}/replay (TEST MODE ONLY)
In test mode (`sec_test_...`), merchants and QA suites can replay stored webhook events to their configured receiver endpoint to verify signature validation, idempotency deduplication, and out-of-order state handling. Calling this endpoint in live mode is refused with HTTP 403 test_mode_only.
mode: "single": Re-delivers the stored event payload once with its originalevt_...ID and a freshPayeny-Signatureheader.mode: "duplicate": Delivers the identicalevt_...event twice back-to-back so you can verify your receiver's idempotency table returns HTTP200without double-processing.mode: "out_of_order": Delivers a sequence of events (orevent_ids: [...]in reverse/out-of-order sequence, e.g.subscription.updatedbeforesubscription.created) to verify your handler reconciles state deterministically.- Sending an Unsigned Webhook Test (
unsigned: true): Pass"unsigned": truein the replay body—or send a directcurl -X POSTto your webhook URL without thePayeny-Signatureheader—to confirm your receiver rejects unsigned requests with HTTP400or401.
# 1. Replay duplicate delivery (verify idempotency dedupe)
curl -s -X POST https://payeny.com/api/v1/events/evt_70f4e47c3a6801cb6c11/replay \
-H "Authorization: Bearer sec_test_..." \
-H "Content-Type: application/json" \
-d '{"mode": "duplicate"}'
# 2. Replay out-of-order delivery
curl -s -X POST https://payeny.com/api/v1/events/evt_70f4e47c3a6801cb6c11/replay \
-H "Authorization: Bearer sec_test_..." \
-H "Content-Type: application/json" \
-d '{"mode": "out_of_order", "event_ids": ["evt_later_update", "evt_earlier_create"]}'
# 3. Send an unsigned webhook test (omits Payeny-Signature header)
curl -s -X POST https://payeny.com/api/v1/events/evt_70f4e47c3a6801cb6c11/replay \
-H "Authorization: Bearer sec_test_..." \
-H "Content-Type: application/json" \
-d '{"mode": "single", "unsigned": true}'
Inbound Stripe Webhook Endpoint
POST /api/v1/stripe/webhook/{merchant_slug}
Each merchant configures its Stripe test workbench to send events to its dedicated inbound endpoint on Payeny (for example, https://payeny.com/api/v1/stripe/webhook/acme).
- Per-Merchant Secret Verification: Payeny loads
STRIPE_WEBHOOK_SECRETfromsecrets/stripe_{merchant_slug}.envand verifies the incomingStripe-Signatureheader. Any missing or invalid signature is rejected immediately with HTTP400 Bad Request. - Event Deduplication: Processed Stripe event IDs (
evt_...) are stored instripe_webhook_eventsso duplicate deliveries return200 {"received":true,"duplicate":true}without double-processing. - State Sync & Outbound Fan-Out: Payeny updates local database records (
checkout_sessions,subscriptions_v2,invoices,refunds_v2) and dispatches the corresponding signed Payeny outbound webhook to the merchant's endpoint.
curl -X POST https://payeny.com/api/v1/stripe/webhook/acme \
-H "Stripe-Signature: t=1792667700,v1=..." \
-H "Content-Type: application/json" \
-d '{"id":"evt_test_123","type":"checkout.session.completed","data":{"object":{"id":"cs_test_123"}}}'