Transaction Review Webhooks

Inspect and approve or deny embedded wallet signing requests from your own backend before Dynamic signs them.

This feature is available for all Dynamic v3 embedded wallets (TSS-MPC). Upgrade is required if you are on v2 or earlier.

Overview

Transaction Review lets you approve or deny embedded wallet signing requests from your own backend before Dynamic signs them. Dynamic sends each signing request to a webhook endpoint you control; your endpoint returns an approve or deny decision.

Transaction Review complements Policies & Rules. Policies enforce rules you configure in the dashboard; Transaction Review delegates the decision to your own service. Both apply before a transaction is signed.

How it works

1. A user initiates a signing operation (EVM transaction, Solana transaction, message signing, or others).
2. Before signing, Dynamic sends a POST request with the signing context to your webhook URL.
3. Your endpoint returns { "proceed": true } to approve, or { "proceed": false, "reason": "..." } to deny.
4. If the request is denied, Dynamic returns a TransactionReviewDenied error to the SDK. The signing is blocked and the transaction is not submitted.

If your webhook is unreachable or times out, the outcome is determined by your configured failure policy.

Configuration

Configure your webhook from the Dynamic dashboard under Wallets → Transaction Review.

Field	Description
Webhook URL	HTTPS endpoint that receives signing requests.
Webhook Secret	Shared secret used to verify requests came from Dynamic. Optional but recommended.
Response Verification Key	Your Ed25519 public key in PEM format. If set, Dynamic verifies your response signature.
Failure Policy	DENY (default) blocks signing if your webhook is unreachable; ALLOW proceeds.

Request format

Dynamic sends a POST request with Content-Type: application/json.

Headers

Header	Description
Content-Type	application/json.
x-dynamic-signature	HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret. Present only if a secret is configured.

Body

{
  "environmentId": "abc123",
  "walletId": "wallet_xyz",
  "userId": "user_abc",
  "shareSetType": "rootUser",
  "message": "0xdeadbeef...",
  "context": {
    "evmTransaction": {
      "chainId": 1,
      "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "value": "0x0",
      "data": "0xa9059cbb...",
      "gas": "0x5208",
      "maxFeePerGas": "0x3b9aca00",
      "maxPriorityFeePerGas": "0x3b9aca00",
      "nonce": "0x5"
    }
  }
}

shareSetType values

Value	Meaning
rootUser	Standard user wallet.
delegated	Delegated signing (server-side on behalf of user).
server	Server-initiated signing.
businessAccountUser	Signer belonging to a business account wallet.

context fields

The context object contains chain-specific transaction details. Only one field is populated per request.

EVM transaction (evmTransaction)

{
  "chainId": 1,
  "to": "0x...",
  "value": "0x...",
  "data": "0x...",
  "gas": "0x...",
  "maxFeePerGas": "0x...",
  "maxPriorityFeePerGas": "0x...",
  "nonce": "0x..."
}

EVM UserOperation (evmUserOperation)

For ERC-4337 account abstraction:

{
  "chainId": 1,
  "sender": "0x...",
  "callData": "0x...",
  "entryPoint": "0x...",
  "operation": { }
}

Solana transaction (svmTransaction)

{
  "chainId": "mainnet-beta",
  "method": "signTransaction",
  "serializedTransactions": ["base64encodedtx..."]
}

Solana message (svmMessage)

A raw base64-encoded message string.

EVM typed data (evmTypedData)

EIP-712 structured data for eth_signTypedData requests.

EVM message (evmMessage)

Plain message signing (personal_sign).

Response format

Your endpoint must return 200 OK with a JSON body.

To approve:

{
  "proceed": true
}

To deny:

{
  "proceed": false,
  "reason": "Transaction blocked by policy: suspicious contract interaction"
}

The reason field is optional but recommended. It appears in Dynamic’s logs and events for debugging.

Your endpoint must respond within 5 seconds. A timeout is treated as a failure and falls back to your failure policy.

Verifying requests (HMAC signature)

If you configure a Webhook Secret, Dynamic includes an x-dynamic-signature header containing an HMAC-SHA256 hex digest of the raw request body. Verify this signature before parsing or acting on the body.

import { createHmac, timingSafeEqual } from 'crypto';
import express, { type Request } from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

// Reusable guard: returns true only when a valid HMAC accompanies the request.
// The rule examples below all call this first.
const isSignatureValid = (req: Request): boolean => {
  const secret = process.env.DYNAMIC_WEBHOOK_SECRET!;
  const signature = req.headers['x-dynamic-signature'] as string | undefined;
  if (!signature) return false;

  const expectedBuf = Buffer.from(createHmac('sha256', secret).update(req.body).digest('hex'), 'hex');
  const receivedBuf = Buffer.from(signature, 'hex');

  return expectedBuf.length === receivedBuf.length && timingSafeEqual(expectedBuf, receivedBuf);
};

app.post('/webhook/transaction-review', (req, res) => {
  if (!isSignatureValid(req)) {
    return res.status(401).json({ proceed: false, reason: 'Invalid signature' });
  }

  const payload = JSON.parse(req.body.toString());
  // ... evaluate payload
  return res.json({ proceed: true });
});

HMAC verification requires the exact raw bytes. Use express.raw({ type: 'application/json' }), not express.json(), and parse the body yourself with JSON.parse(req.body.toString()). express.json() mutates the payload (whitespace and key order) and breaks signature verification. The rule examples below reuse the same raw-body setup and the isSignatureValid guard defined here. Always verify the signature before parsing or acting on the body.

Signing responses (Ed25519)

If you configure a Response Verification Key, Dynamic verifies that your webhook response was signed with the corresponding Ed25519 private key. This prevents response tampering by an intermediary.

Generating a key pair

# Generate Ed25519 private key
openssl genpkey -algorithm ed25519 -out private.pem

# Extract public key (paste this into the Dynamic dashboard)
openssl pkey -in private.pem -pubout -out public.pem

Signing your response

Your endpoint must include an x-dynamic-response-signature header containing the Base64-encoded Ed25519 signature of the raw response body bytes.

import { createPrivateKey, sign } from 'crypto';
import { readFileSync } from 'fs';
import express from 'express';

const app = express();
const privateKeyPem = readFileSync('./private.pem', 'utf8');
const privateKey = createPrivateKey(privateKeyPem);

app.post('/webhook/transaction-review', (req, res) => {
  const responseBody = JSON.stringify({ proceed: true });
  const signature = sign(null, Buffer.from(responseBody), privateKey);

  res.setHeader('x-dynamic-response-signature', signature.toString('base64'));
  res.setHeader('Content-Type', 'application/json');
  res.send(responseBody);
});

Sign the raw bytes of the response body exactly as sent. Do not re-serialize. Any difference in whitespace or key ordering fails verification.

Failure policy

The failure policy determines the outcome when your webhook is unreachable or times out.

Policy	Behavior when the webhook is unreachable or times out
DENY (default)	Signing is blocked; the user receives a TransactionReviewDenied error.
ALLOW	Signing proceeds as if approved.

Choose ALLOW only if you prefer availability over strict enforcement and trust your infrastructure to handle outages.

Events

Dynamic emits events you can subscribe to via webhooks for observability.

Event	Description
waas.transaction.review.approved	Transaction review passed; signing will proceed.
waas.transaction.review.denied	Transaction review denied; signing was blocked.

Example: Block transactions to specific contracts

import express from 'express';

const BLOCKED_CONTRACTS = new Set([
  '0xdeadbeef...', // known malicious contract
]);

app.post('/webhook/transaction-review', express.raw({ type: 'application/json' }), (req, res) => {
  // Always verify the signature before parsing or acting on the body
  // (reuses the `isSignatureValid` guard from "Verifying requests" above).
  if (!isSignatureValid(req)) {
    return res.status(401).json({ proceed: false, reason: 'Invalid signature' });
  }

  const { context } = JSON.parse(req.body.toString());

  const targetContract = context.evmTransaction?.to?.toLowerCase();

  if (targetContract && BLOCKED_CONTRACTS.has(targetContract)) {
    // Log the specific target server-side; keep the response `reason` a fixed
    // string so request-controlled input is never reflected back to the caller.
    console.warn('Blocked transaction to contract', { targetContract });
    return res.json({
      proceed: false,
      reason: 'Transaction to a blocked contract',
    });
  }

  return res.json({ proceed: true });
});

Example: Solana — inspect program instructions

import { Transaction } from '@solana/web3.js';

app.post('/webhook/transaction-review', express.raw({ type: 'application/json' }), (req, res) => {
  // Always verify the signature before parsing or acting on the body
  // (reuses the `isSignatureValid` guard from "Verifying requests" above).
  if (!isSignatureValid(req)) {
    return res.status(401).json({ proceed: false, reason: 'Invalid signature' });
  }

  const { context } = JSON.parse(req.body.toString());

  if (context.svmTransaction) {
    const { serializedTransactions } = context.svmTransaction;

    for (const serialized of serializedTransactions) {
      const txBuffer = Buffer.from(serialized, 'base64');
      const tx = Transaction.from(txBuffer);

      for (const instruction of tx.instructions) {
        const programId = instruction.programId.toBase58();

        if (programId !== 'YourExpectedProgramId111111111111111111111') {
          // Log the specific program server-side; keep the response `reason` a
          // fixed string so request-controlled input isn't reflected back.
          console.warn('Unexpected Solana program interaction', { programId });
          return res.json({
            proceed: false,
            reason: 'Unexpected program interaction',
          });
        }
      }
    }
  }

  return res.json({ proceed: true });
});

Testing your webhook

Use a tool like ngrok to expose a local server during development:

ngrok http 3000

Set the generated HTTPS URL as your webhook URL in the Dynamic dashboard. Use a sandbox environment to test without affecting production.

Dashboard test panel

Once your webhook URL is in the form, the Transaction Review side panel exposes a Test webhook card with a scenario dropdown and a Send test button. Select a scenario (Sign message, EVM transaction, EVM token transfer, EVM user operation, EVM typed data, or Solana transaction) and click Send test to drive a synthetic payload through the same HMAC signing, response signature verification, timeout, and failure-policy code paths as live signing. The test panel emits no events, performs no signing, and writes nothing to the database.

The result panel shows the decision, latency, HTTP status, signature verification state, and the full request and response bodies, so you can iterate on your endpoint without issuing a real transaction.

To simulate a denied response and verify your SDK error handling:

// This stub never reads the request body, so the body-parsing middleware
// choice doesn't matter here. Once you add HMAC verification, switch to the
// `express.raw({ type: 'application/json' })` setup shown above.
app.post('/webhook/transaction-review', (_req, res) => {
  // Deny everything in test mode
  res.json({ proceed: false, reason: 'Test denial' });
});

The SDK surfaces this as:

TransactionReviewDenied: Test denial

Reference implementation

For a complete, runnable starting point, see the Transaction Review webhook example server. It verifies inbound HMAC signatures, optionally Ed25519-signs responses, and exposes hot-switchable allow, deny, slow, and crash modes for end-to-end testing against the dashboard test panel.