Stripe Webhook Verifier

AEVION exposes a thin verifier for Stripe webhook signatures so partner services can re-confirm event authenticity before acting on them. This is independent of Stripe's own signature scheme — it's a second-factor that anchors webhook events into the AEVION settlement layer.

How it works

Stripe POSTs an event to your endpoint with a Stripe-Signature header. You verify against Stripe (HMAC-SHA256 with your STRIPE_WEBHOOK_SECRET), then optionally re-anchor to AEVION via POST /api/qpaynet/stripe/verify. The AEVION verifier returns ok: trueonly if the event payload + Stripe-signature combination is verifiable and the event hasn't already been processed.

1. Verify with Stripe SDK (Node)

import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const sig = request.headers["stripe-signature"];
const event = stripe.webhooks.constructEvent(
  rawBody,
  sig,
  process.env.STRIPE_WEBHOOK_SECRET!
);
// At this point Stripe's signature has verified. Now anchor to AEVION:

2. Re-anchor with AEVION verifier

const r = await fetch("https://api.aevion.app/api/qpaynet/stripe/verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.AEV_TOKEN}`,
  },
  body: JSON.stringify({
    event_id: event.id,
    event_type: event.type,
    raw_payload: rawBody,
    stripe_signature: sig,
  }),
});
const result = await r.json();
// result: { ok: true, anchored: true, veilnetx_id: "...", idempotent: false }
// Idempotent=true means this event was already processed.

3. Python equivalent

import stripe, requests, os
stripe.api_key = os.environ["STRIPE_SECRET_KEY"]
sig = request.headers.get("Stripe-Signature")
event = stripe.Webhook.construct_event(
    raw_body, sig, os.environ["STRIPE_WEBHOOK_SECRET"]
)
r = requests.post(
    "https://api.aevion.app/api/qpaynet/stripe/verify",
    headers={"Authorization": f"Bearer {os.environ['AEV_TOKEN']}"},
    json={
        "event_id": event.id,
        "event_type": event.type,
        "raw_payload": raw_body.decode(),
        "stripe_signature": sig,
    },
)
print(r.json())

4. Idempotency

The verifier deduplicates by event_id— Stripe's globally-unique event identifier. Replaying the same event later (e.g., via Stripe's "Resend" button) returns idempotent: true and does not double-anchor to VeilNetX. This makes it safe to call the verifier from inside your webhook handler even on retries.

5. Failure modes

• 401 — missing or invalid Bearer token
• 400 — malformed body, missing fields, or signature mismatch
• 409 — event already processed (idempotency conflict, rare)
• 500 — verifier-side error; safe to retry with exponential backoff

Related endpoints

• POST /api/qpaynet/deposit — initiate Stripe checkout, returns session URL
• POST /api/qpaynet/stripe/webhook — Stripe's direct callback target
• GET /api/qpaynet/me/deposits — your deposit history (auth required)