Webhook Delivery

YoorQuezt delivers real-time event notifications to your registered webhook endpoints via HTTP POST. Each delivery includes an HMAC-SHA256 signature for verification.

Event Types

The following events are currently implemented:

Additional event types are planned for future releases:

Webhook Payload

{
  "id": "evt_abc123def456",
  "event": "tx.protected",
  "timestamp": "2026-03-15T12:34:56Z",
  "data": {
    "tx_hash": "0x1234...",
    "chain": "ethereum",
    "block_number": 19500000,
    "backrun_tx": "0x5678...",
    "captured_value": "0.003241",
    "rebate_amount": "0.002917",
    "rebate_token": "ETH"
  }
}

Signature Verification

Every webhook delivery includes an X-YQ-Signature header containing an HMAC-SHA256 signature of the request body. Verify this signature using your webhook secret to ensure the payload is authentic.

The signature is computed as:

HMAC-SHA256(webhook_secret, raw_request_body)

The header value is hex-encoded:

X-YQ-Signature: sha256=a1b2c3d4e5f6...

Verification Steps

1. Read the raw request body (do not parse JSON first).
2. Compute HMAC-SHA256(webhook_secret, raw_body).
3. Compare the computed hex digest with the value after sha256= in the header.
4. Use a constant-time comparison to prevent timing attacks.

Retry Policy

If your endpoint returns a non-2xx status code or times out, YoorQuezt retries the delivery with exponential backoff:

After 5 failed attempts, the delivery is marked as failed. You can replay failed deliveries from the dashboard.

Express.js Example

import express from "express";
import crypto from "crypto";

const app = express();

// Use raw body for signature verification
app.use("/webhooks/yoorquezt", express.raw({ type: "application/json" }));

const WEBHOOK_SECRET = process.env.YQ_WEBHOOK_SECRET;

function verifySignature(payload, signature) {
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");

  const sig = signature.replace("sha256=", "");

  return crypto.timingSafeEqual(
    Buffer.from(sig, "hex"),
    Buffer.from(expected, "hex")
  );
}

app.post("/webhooks/yoorquezt", (req, res) => {
  const signature = req.headers["x-yq-signature"];

  if (!signature || !verifySignature(req.body, signature)) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const event = JSON.parse(req.body);

  switch (event.event) {
    case "tx.protected":
      console.log(`Transaction protected: ${event.data.tx_hash}`);
      break;
    case "tx.included":
      console.log(`Transaction included in block ${event.data.block_number}`);
      break;
    case "tx.failed":
      console.log(`Transaction failed: ${event.data.tx_hash} - ${event.data.reason}`);
      break;
    default:
      console.log(`Unhandled event: ${event.event}`);
  }

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

app.listen(3000, () => {
  console.log("Webhook server listening on port 3000");
});