Webhook Best Practices

The rules below are written so your handler keeps working as new event types and fields arrive - see Events & Payloads for the event catalog.

1. Respond before you process

Return a 2xx immediately, then do the work asynchronously. WalletSuite only acknowledges a delivery on a 2xx in time. If you verify the signature, then write to your database, call a third-party API, and then respond, a slow dependency turns into a delivery timeout, which turns into a retry, which turns into a duplicate. The correct shape: verify the signature, enqueue the event, return 200. Process from the queue.

Express

import express from "express";

const app = express();

app.post(
  "/webhooks/walletsuite",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    if (!verifySignature(req)) {
      return res.status(400).send("invalid signature");
    }

    await queue.enqueue(req.body.toString("utf8"));

    res.status(200).send("ok");
  }
);

2. Be idempotent

Dedupe on event_id with a database unique constraint: the first delivery processes; every later delivery of the same event is a no-op. Delivery is at-least-once, so dedupe on your idempotency key - the event_id (= the Webhook-Id header). A naive “have I seen this id?” check has a race: two concurrent deliveries both read “not seen,” both process. A conditional insert under a unique constraint closes it - exactly one delivery wins the insert and processes; the rest see the conflict and return.

Postgres

CREATE TABLE processed_events (
  event_id  uuid PRIMARY KEY,
  seen_at   timestamptz NOT NULL DEFAULT now()
);

Node + Postgres (pg)

async function handleEvent(event: WebhookEvent) {
  const claim = await pool.query(
    `INSERT INTO processed_events (event_id)
       VALUES ($1)
     ON CONFLICT (event_id) DO NOTHING
     RETURNING event_id`,
    [event.event_id]
  );

  if (claim.rowCount === 0) {
    return;
  }

  await applyBusinessLogic(event);
}

3. Don’t assume order

Use occurred_at for temporal logic, never arrival order. Delivery order is best-effort, not guaranteed. Process each event independently. When you need to reason about when something happened on-chain - “is this the most recent transfer?”, “did this arrive before that?” - compare the occurred_at field, not the order packets reached your server.

if (event.occurred_at > state.latestBalanceEventTime) {
  state.latestBalanceEventTime = event.occurred_at;
}

4. Tolerate the unknown

Write tolerant parsers so new capabilities arrive without a redeploy. The payload versioning contract guarantees additive evolution within your pinned schema_version, and enums are open. A handler that acknowledges what it doesn’t recognize - new fields, types, and enum values - keeps working as the schema grows.

function route(event: WebhookEvent) {
  if (event.event_type !== "transfer.received") return;

  switch (event.data.asset_type) {
    case "native":
      return creditNative(event);
    case "erc20":
    case "trc20":
      return creditToken(event);
    default:
      log.info("unhandled asset_type", { type: event.data.asset_type });
      return;
  }
}

5. Treat webhooks as signals, not the ledger

Re-query authoritative state before any high-value action. A webhook is a low-latency signal that something happened - it is not your source of truth. Before you credit a large balance, release goods, or trigger a payout, confirm the transfer by reading current state from the REST API. This is defense-in-depth on two fronts:

Against stale data - signature verification proves origin; re-querying proves the transfer is real, final, and still reflected in current state.
Against gaps - deliveries retry across the full retry window, and a periodic reconciliation sweep that re-queries the API guarantees correctness even if your endpoint is down past it.

async function onTransfer(event: WebhookEvent) {
  const { chain, to, asset_type, asset_contract } = event.data;

  const balance = await sdk.api.getAssetBalances(to, {
    chain,
    assetIds: asset_type === "native" || !asset_contract ? [] : [asset_contract],
    includeNative: asset_type === "native",
  });

  if (confirmsExpectedCredit(balance.data, event)) {
    await releaseGoods(event);
  }
}

6. Store the secret securely

Keep whsec_… in a secret manager - never in code - and rotate via the API. Treat it exactly like an API key (see Securing Your API Keys). Rotate it if it’s ever exposed - see secret rotation.

Verify Signatures

Full copy-paste verification code, in multiple languages.

Delivery & Retries

The retry ladder, timeouts, and at-least-once semantics behind these rules.

Events & Payloads

Field-by-field reference for the transfer.received payload.

Quickstart

Subscribe, provision a secret, and receive your first event.

​1. Respond before you process

​2. Be idempotent

​3. Don’t assume order

​4. Tolerate the unknown

​5. Treat webhooks as signals, not the ledger

​6. Store the secret securely

​Related

Verify Signatures

Delivery & Retries

Events & Payloads

Quickstart

1. Respond before you process

2. Be idempotent

3. Don’t assume order

4. Tolerate the unknown

5. Treat webhooks as signals, not the ledger

6. Store the secret securely

Related