Webhooks - My Crypto Server

Webhooks let My Crypto Server notify your server when events happen — like when a payment is confirmed. You register an HTTPS endpoint, subscribe to event types, and we POST a signed JSON payload to your URL.

Event types

Event	When it fires
`session.paid`	Payment confirmed with the required number of confirmations
`session.paid_late`	Payment confirmed after the session expired (within the grace window)
`session.expired`	Session timed out with no payment detected
`session.underpaid`	A transfer was detected but the amount is less than required
`session.overpaid`	A transfer was detected for more than the required amount
`session.detected`	First transfer detected (before finality confirmation)

Registering an endpoint

Create a webhook endpoint via the API or the dashboard.

curl -X POST https://your-domain.com/api/v1/webhook_endpoints \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-webhook-setup-v1" \
  -d '{
    "url": "https://your-server.com/webhooks/crypto",
    "events": ["session.paid", "session.expired"]
  }'

The response includes a secret field — copy it immediately, it is never shown again. You use this to verify incoming webhook signatures.

{
  "id": "wh_...",
  "object": "webhook_endpoint",
  "url": "https://your-server.com/webhooks/crypto",
  "events": ["session.paid", "session.expired"],
  "active": true,
  "secret": "whsec_...",
  "secretPrefix": "whsec_ab",
  "createdAt": "2024-01-01T00:00:00Z"
}

Webhook payload

Each delivery is a POST with a JSON body containing an Event object:

{
  "id": "evt_01HQXYZ...",
  "object": "event",
  "type": "session.paid",
  "livemode": true,
  "data": {
    "id": "cs_01HQABC...",
    "status": "paid",
    "txHash": "0xabc123...",
    "amount": { "wei": "50000000000000000", "eth": "0.05" },
    "fiat": { "amount": "100.00", "currency": "USD" }
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Verifying signatures

Every delivery includes two headers:

X-Webhook-Signature: t=1705312200,v1=abc123...
X-Webhook-Timestamp: 1705312200

The signed string is ${timestamp}.${rawBody} — HMAC-SHA256 with your endpoint’s secret. Always verify the signature before processing a webhook.

Using the SDK

import { verifyWebhook } from "@your-org/checkout-sdk/webhooks";

// Express example
app.post("/webhooks/crypto", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = verifyWebhook({
      payload: req.body.toString(),
      signature: req.headers["x-webhook-signature"],
      timestamp: req.headers["x-webhook-timestamp"],
      secret: process.env.CHECKOUT_WEBHOOK_SECRET!,
    });
  } catch (err) {
    return res.status(400).send("Invalid signature");
  }

  if (event.type === "session.paid") {
    const session = event.data;
    // Fulfill the order for session.metadata.orderId
    await fulfillOrder(session.metadata.orderId, session.txHash);
  }

  res.json({ received: true });
});

Manual verification (Node.js)

const crypto = require("node:crypto");

const rawBody = req.body.toString();
const sigHeader = req.headers["x-webhook-signature"];
const [tPart, v1Part] = sigHeader.split(",");
const ts = tPart.split("=")[1];
const v1 = v1Part.split("=")[1];

// Reject stale webhooks (>5 min)
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
  throw new Error("Webhook timestamp outside tolerance window");
}

const expected = crypto
  .createHmac("sha256", process.env.CHECKOUT_WEBHOOK_SECRET)
  .update(`${ts}.${rawBody}`)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v1, "hex"))) {
  throw new Error("Webhook signature mismatch");
}

const event = JSON.parse(rawBody);

Delivery and retries

My Crypto Server expects a 2xx response within 30 seconds. If your server doesn’t respond or returns a non-2xx status, delivery is retried with exponential backoff — up to 6 attempts over approximately 31 hours. You can replay any delivery from the dashboard under Webhooks → Deliveries.

Testing

Use the test endpoint to fire a synthetic session.paid event to your registered URL without needing an actual payment:

curl -X POST https://your-domain.com/api/v1/webhook_endpoints/{id}/test \
  -H "Authorization: Bearer ck_live_..."

​Event types

​Registering an endpoint

​Webhook payload

​Verifying signatures

​Using the SDK

​Manual verification (Node.js)

​Delivery and retries

​Testing