Webhooks Overview

Quasar acts as a headless engine, meaning you often need to know when asynchronous events complete in the background. Webhooks are the primary mechanism Quasar uses to push real-time event data back to your integrator backend.

What is a Webhook?

Instead of constantly polling the Quasar API to check if a transaction has mined, you provide Quasar with an HTTP endpoint (e.g., https://api.myapp.com/webhooks/quasar). When a specific event occurs, Quasar automatically sends an HTTP POST request to your endpoint containing a JSON payload describing the event.

Creating a Webhook

You must create and configure your Webhooks through the dashboard:

1. Log in to the Quasar Dashboard .
2. Ensure you are in your target Organization.
3. Navigate to Webhooks.
4. Click Add Webhook and provide your target URL endpoint.
5. Select the specific Events (triggers) you want this webhook to listen for.

Once created, Quasar will immediately begin dispatching events to your URL.

Event Triggers

Webhooks in Quasar are tightly scoped to specific events within the TUWA ecosystem. The most common triggers include:

• transaction.success: Triggered if the transaction mined successfully and is confirmed on the blockchain.
• transaction.failed: Triggered if the transaction reverts or fails during execution.
• transaction.replaced: Triggered if the transaction replaces another transaction.

Delivery Headers

Every webhook POST request is dispatched with the following standard L7 headers:

Payload Structure

When an event triggers, Quasar dispatches a structured JSON payload containing transaction properties and custom payload data:

{
  "txKey": "tx_local_18f2...",
  "hash": "0xabc123...",
  "status": "Success",
  "action": "Success",
  "txType": "TRANSFER",
  "chainId": "1",
  "timestamp": 1779374022,
  "payload": {
    "customField": "arbitraryValue"
  }
}

Why do I need a Webhook Secret?

When you create a webhook in the dashboard, Quasar generates a unique Webhook Secret (e.g., whsec_...).

[!IMPORTANT] The Webhook Secret is used to securely verify that incoming POST requests actually came from Quasar and not a malicious third party pretending to be Quasar.

Whenever Quasar dispatches a payload, it uses your Webhook Secret to generate a cryptographic hash (HMAC SHA-256) of the payload. It attaches this hash in the headers of the POST request (typically x-quasar-signature).

Your backend must intercept the incoming request, generate its own hash using the raw payload body and your stored Webhook Secret, and compare the two hashes. If they match, the payload is authentic.

Webhook Receiver Example

Here is a complete Next.js Route Handler (App Router) example showing how to verify and accept incoming webhook deliveries from Quasar:

import { NextRequest, NextResponse } from 'next/server';
import crypto from 'crypto';
 
export async function POST(req: NextRequest) {
  const signature = req.headers.get('x-quasar-signature');
  const secret = process.env.QUASAR_WEBHOOK_SECRET;
 
  if (!signature || !secret) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }
 
  // Get raw body as text to ensure signature validation works correctly
  const rawBody = await req.text();
 
  // Generate signature using HMAC SHA-256
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
 
  // Compare signatures securely using timingSafeEqual
  const signatureBuffer = Buffer.from(signature, 'utf8');
  const computedBuffer = Buffer.from(computedSignature, 'utf8');
 
  if (
    signatureBuffer.length !== computedBuffer.length ||
    !crypto.timingSafeEqual(signatureBuffer, computedBuffer)
  ) {
    return NextResponse.json({ error: 'Invalid signature' }, { status: 401 });
  }
 
  // Parse and process the authenticated payload
  const payload = JSON.parse(rawBody);
  
  // Note: Standard Quasar webhooks contain details like event and data
  // e.g. payload.event === 'transaction.success'
  
  return NextResponse.json({ success: true }, { status: 200 });
}

Rolling / Rotated Webhook Secrets

If you suspect your Webhook Secret has been compromised, or as part of standard security compliance, you can rotate/roll the signing secret through the Quasar Dashboard:

1. Navigate to Webhooks in the Dashboard.
2. Select your webhook endpoint configuration.
3. Under Security, click Roll Secret.
4. To prevent unauthorized rotation, you will be prompted for Step-Up Authentication (password and 2FA code if enabled).
5. Once verified, a new whsec_... signing secret is generated and displayed.

[!WARNING] Immediate Effect: Rolling a webhook secret instantly invalidates the old one. Quasar will immediately begin signing outgoing payloads with the new secret. Ensure your backend webhook receiver is updated with the new environment variable promptly to prevent delivery verification failures.

Note that global multi-region edge caches might take up to 60 seconds to propagate the eviction. Allow a 1-minute window for the new secret to propagate fully.

Webhook Delivery & Retries

To ensure reliable delivery even during brief outages of your backend receiver, Quasar employs a resilient message queue system powered by BullMQ:

• Maximum Retries: Quasar attempts to deliver each webhook up to 10 times before marking the delivery as failed.
• Exponential Backoff: If a delivery fails, Quasar schedules retries using an exponential backoff formula, beginning with a 5-second initial delay.
• SSRF and Redirect Blocking: For infrastructure security, redirects are strictly forbidden (redirect: 'error'). Any endpoint attempting to return a redirect response (3xx) will trigger an immediate delivery failure.
• Quota Auditing: Quasar accounts for usage on the first delivery attempt only. Retries do not consume additional organization quota units.
• Data Masking in Logs: The dashboard exposes the last 1,000 delivery failures for troubleshooting. To safeguard secrets, Quasar scans and masks all sensitive keys (e.g. secret, token, password, key, privatekey, credential) inside the stored request payloads and response bodies.

Next, see the Security & Signatures page for deep details on how Quasar protects webhook deliveries.