Delegation Flow

What happens when a user approves delegation and how to handle the webhook.

Recommended: JavaScript SDK with React Hooks

For new React apps, we recommend the JavaScript SDK with React Hooks (@dynamic-labs-sdk/react-hooks) instead of the legacy React SDK documented here. The JS SDK comes with many benefits such as a much smaller bundle size and other optimizations. Use the React quickstart (JavaScript SDK) to get started.

Server-only
This page covers your server webhook handler. The client triggers delegation; your server verifies, decrypts, and stores materials.

When a delegation is triggered, your endpoint receives a webhook named wallet.delegation.created. The delegated materials are in data.

{
  "messageId": "f44da9f0-a5b5-47f6-965f-f04af51c903e",
  "eventId": "2cf779a8-89da-486f-974e-2b77b738e4ac",
  "eventName": "wallet.delegation.created",
  "timestamp": "2025-10-01T15:13:26.348Z",
  "webhookId": "9a31fefc-64e4-4551-81da-1502eacc852d",
  "userId": "7eb7843b-2a4d-4f69-b95e-d219f0662fda",
  "environmentId": "53728749-1f19-4cab-becf-b88f952c3a3c",
  "environmentName": "sandbox",
  "data": {
    "chain": "EVM",
    "encryptedDelegatedShare": {
      "alg": "HYBRID-RSA-AES-256",
      "iv": "dzePdAUMQd6lWQngEXWPdQ",
      "ct": "pJIT5UU...XcWeYsXhygL2QbQcWZK6Rs5_CuiCDb_dHC_7P1tC...",
      "tag": "Yq8bpMU8huIx7UzUUUgI9Q",
      "ek": "uix2E6E...Keru7HWqeu7ktw"
    },
    "encryptedWalletApiKey": {
      "alg": "HYBRID-RSA-AES-256",
      "ct": "PzeliI...0kB9C0",
      "ek": "iWJgZQ...rxt",
      "iv": "RpC5nw1b4udgJqnC1p0evQ",
      "kid": "dynamic_rsa_lSuvWlCy",
      "tag": "-ZtmOG6gYTzS53wVMNK0Ig"
    },
    "publicKey": "0xd74ff800a3c6f66ecd217118aaa6fb1c916fa4e2",
    "userId": "7eb7843b-2a4d-4f69-b95e-d219f0662fda",
    "walletId": "25193936-3ecd-4c1b-84e6-9eabc82e53c2"
  }
}

Verify → Decrypt → Store

1. Verify the webhook signature. Use your webhook secret and the x-dynamic-signature-256 header: compute HMAC-SHA256 of the raw request body with the secret and compare to the header value in constant time. Only proceed if the signature is valid.

import * as crypto from "crypto";

export const verifySignature = ({
  secret,
  signature,
  payload,
}: { secret: string; signature: string; payload: any }) => {
  const payloadSignature = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(payload))
    .digest("hex");
  const trusted = Buffer.from(`sha256=${payloadSignature}`, "ascii");
  const untrusted = Buffer.from(signature, "ascii");
  return crypto.timingSafeEqual(trusted, untrusted);
};

The payload you pass to verifySignature must match exactly how it was sent (same JSON structure); otherwise verification will fail.

2. Decrypt data.encryptedDelegatedShare and data.encryptedWalletApiKey.
3. Store userId, walletId, and decrypted materials securely (e.g., envelope encryption, KMS, at-rest encryption).

Encryption fields
alg: hybrid (RSA‑OAEP + AES‑256‑GCM); iv: AES IV; ct: ciphertext; tag: GCM tag; ek: encrypted content‑encryption key; kid: key identifier for rotation.

Example: Node (using Dynamic SDK)

We provide a helper function to handle decryption for you. Install the SDK:

npm install @dynamic-labs-wallet/node

Then use the decryptDelegatedWebhookData function:

import { decryptDelegatedWebhookData } from '@dynamic-labs-wallet/node';

// In your webhook handler, after verifying the signature
const webhookData = req.body; // The webhook payload

const { decryptedDelegatedShare, decryptedWalletApiKey } =
  decryptDelegatedWebhookData({
    privateKeyPem: process.env.YOUR_PRIVATE_KEY, // Your RSA private key
    encryptedDelegatedKeyShare: webhookData.data.encryptedDelegatedShare,
    encryptedWalletApiKey: webhookData.data.encryptedWalletApiKey,
  });

// Now securely store these decrypted materials
// decryptedDelegatedShare: ServerKeyShare object
// decryptedWalletApiKey: string

If a delivery fails, you can replay it from the dashboard. Use the eventId as an idempotency key.

---

Storage Best Practices

Learn how to securely store decrypted delegated materials.

Developer Actions

Learn how to use the delegated materials.