Webhooks

Set up an endpoint

Tell us an https URL for each mode at support@flipeet.io. If you don’t give a sandbox URL, sandbox events go to your live URL, signed with the sandbox secret. You can also pass callbackUrl on a single deposit or withdrawal to send its events somewhere else. Reply with any 2xx status within 10 seconds. Do slow work, like sending emails, after you reply.

Events

Event	When
`checkout.completed`	A checkout was paid.
`transaction.crypto.completed`	A crypto deposit arrived.
`transaction.fiat.completed`	A bank deposit cleared and was settled.
`transaction.fiat.failed`	A bank deposit failed or expired.
`transaction.withdrawal.completed`	A withdrawal was delivered.
`transaction.withdrawal.failed`	A withdrawal failed and was returned to your balance.
`webhook.test`	You sent a test event.

The event name is in the body’s event field and in the x-flipeetpay-event header. Every event has reference and livemode. Ramp orders are described by their status instead.

Headers

Header	Holds
`x-flipeetpay-signature-v2`	`t=<unix seconds>,v1=<signature>`. Verify this one.
`x-flipeetpay-signature`	HMAC-SHA256 of the body alone, for integrations built before v2.
`x-flipeetpay-timestamp`	When we signed it, in Unix seconds.
`x-flipeetpay-event`	The event name.
`x-flipeetpay-mode`	`live` or `sandbox`.
`x-flipeetpay-delivery`	A unique ID for this delivery.

Verify signatures

Each mode has its own signing secret, which we send with your key. The v2 signature is an HMAC-SHA256, keyed with that secret, of the timestamp, a full stop, and the raw body. Because the timestamp is signed, you can refuse old deliveries that someone replays.

import crypto from "node:crypto";

/**
 * header: the x-flipeetpay-signature-v2 header, "t=<seconds>,v1=<hex>"
 * rawBody: the request body exactly as received, before JSON parsing
 */
export function verifyFlipeetWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    (header ?? "").split(",").map((part) => part.split("=")),
  );
  const timestamp = Number(parts.t);
  if (!timestamp || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
    return false; // missing, or too old: could be a replay
  }
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const given = Buffer.from(parts.v1 ?? "");
  return given.length === expected.length &&
    crypto.timingSafeEqual(given, Buffer.from(expected));
}

import hashlib
import hmac
import time

def verify_flipeet_webhook(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    """header is x-flipeetpay-signature-v2: "t=<seconds>,v1=<hex>"."""
    parts = dict(part.split("=", 1) for part in (header or "").split(",") if "=" in part)
    try:
        timestamp = int(parts["t"])
    except (KeyError, ValueError):
        return False
    if abs(time.time() - timestamp) > tolerance:
        return False  # too old: could be a replay
    expected = hmac.new(
        secret.encode(), f"{timestamp}.".encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

Use the raw body. Parsing the JSON and encoding it again changes the bytes, and the check fails. In Express, use express.raw() on this route.
Compare in constant time, as above, not with ===.
Reject anything older than five minutes.

When we roll your webhook secret, the old one stops working at once. Ask us to roll it only when you’re ready to put the new one on your server.

Retries and duplicates

If your endpoint doesn’t answer with 2xx, we try again: deposit, withdrawal and ramp events after 5 and 30 seconds, and checkout events after 2 seconds. After that the delivery is marked failed. Find it with List webhook deliveries and send it again with Resend a webhook. You may get the same event more than once. Use reference and event to make handling it twice harmless, for example by marking an order paid only if it isn’t already.

Test your endpoint

curl -X POST "https://api.pay.flipeet.io/api/v1/webhook/test" \
  -H "x-api-key: $FLIPEET_SECRET_KEY"

const response = await fetch("https://api.pay.flipeet.io/api/v1/webhook/test", {
  method: "POST",
  headers: {
    "x-api-key": process.env.FLIPEET_SECRET_KEY,
  },
});
const { data } = await response.json();

import os
import requests

response = requests.post(
    "https://api.pay.flipeet.io/api/v1/webhook/test",
    headers={"x-api-key": os.environ["FLIPEET_SECRET_KEY"]},
)
data = response.json()["data"]

webhook.test

{
  "event": "webhook.test",
  "livemode": false,
  "reference": "webhook-test-1762250400000",
  "message": "This is a test webhook from Flipeet Pay.",
  "sentAt": "2026-11-04T10:00:00.000Z"
}

Get started

Get paid

Move money

Build reliably

Set up an endpoint

Events

Headers

Verify signatures

Retries and duplicates

Test your endpoint