Chainhooks (SDK)

The SDK exposes chainhook registration, status lookup, and lifecycle control. Chainhook event processing itself happens server-side in rt-api. All methods resolve to ApiResponse<T>.

Registration

`rtClient.chainhooks.registerEditionTracking(contractName, contractDeployer, options?)`

Register edition tracking for a deployed product contract - the most common case. options.network selects the Hiro environment. Returns ApiResponse<ChainhookRegistrationResponse>.

const { data } = await rtClient.chainhooks.registerEditionTracking(
  "haiku-1701234567",
  user.stxAddress,
  { network: "testnet" },
);

registerEventListing(contractName, contractDeployer, options?) does the same for EVENT-listing hooks, and registerPageChainhook(request) takes the full ChainhookRegistrationRequest ({ contractName, contractDeployer, network, type? }).

Status

`rtClient.chainhooks.getChainhookStatus(params)`

Look up a chainhook by any one of pageId, eventId, uuid, or chainhookId. Pass live: true to also fetch the current predicate state from Hiro. Returns the stored row plus a health block and optional liveStatus.

const { data } = await rtClient.chainhooks.getChainhookStatus({ uuid, live: true });
console.log(data.health.isHealthy);

Lifecycle

network is required on these - the mainnet and testnet chainhook services are separate.

// Enable / disable (recovery from interrupted state)
await rtClient.chainhooks.enableChainhook(uuid, true, "testnet");

// Delete (cleanup for failed deploys or unwanted hooks)
await rtClient.chainhooks.deleteChainhook(uuid, "testnet");

// Re-evaluate against a block (testing)
await rtClient.chainhooks.evaluateChainhook(uuid, "testnet", { block_height: 12345 });

// Retry a failed registration (operator only: the signed-in user's role must hold the entitlement)
await rtClient.chainhooks.retryById(chainhookId);

Operator surface

listAdmin(params?) and getAdminHealth() are operator surfaces, authorized on the signed-in user's role rather than on the key. An app-scoped key alone cannot call them.

Debugging sync issues

If a smart product or instance is not reflecting the expected on-chain state:

Check the block explorer for the transaction status.
Call getChainhookStatus({ uuid, live: true }) and inspect the health block.
Check getAdminHealth() for recent errors and the last inbound timestamp.
Re-register, or retry a failed hook with retryById(chainhookId).

Common causes of sync delays:

Transaction is pending (not yet confirmed).
Chainhook webhook delivery failed (will retry).
Transaction was rejected on-chain.