stacks-network · huth-stacks · Mar 24, 2026
diff --git a/docs/build/SUMMARY.md b/docs/build/SUMMARY.md
@@ -81,6 +81,22 @@
 * [Implementation](post-conditions/implementation.md)
 * [Examples](post-conditions/examples.md)
 
+## Chainhooks <a href="#chainhooks" id="chainhooks"></a>
+
+* [Overview](chainhooks/overview.md)
+* [Introduction](chainhooks/quickstart.md)
+* [Create Chainhooks](chainhooks/create.md)
+* [Fetch Chainhooks](chainhooks/fetch.md)
+* [Edit Chainhooks](chainhooks/update.md)
+* [Replay a Block](chainhooks/evaluate.md)
+* [Manage Secrets](chainhooks/secrets.md)
+* [Migration Guide](chainhooks/migration.md)
+* [FAQ](chainhooks/faq.md)
+* [Reference](chainhooks/reference/README.md)
+  * [Filters](chainhooks/reference/filters.md)
+  * [Options](chainhooks/reference/options.md)
+  * [Payload Anatomy](chainhooks/reference/payload-anatomy.md)
+
 ## More Guides
 
 * [sBTC](more-guides/sbtc/README.md)

diff --git a/docs/build/chainhooks/create.md b/docs/build/chainhooks/create.md
@@ -0,0 +1,141 @@
+---
+description: Create and activate chainhooks using the Chainhooks SDK
+---
+
+# Create chainhooks
+
+{% hint style="info" %}
+This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/tools/chainhooks/create).
+{% endhint %}
+
+Creates a new chainhook configuration. By default, new chainhooks are created in a disabled state unless `enable_on_registration` is set to `true`.
+
+## registerChainhook
+
+### Example
+
+```ts
+import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client';
+
+const client = new ChainhooksClient({
+  baseUrl: CHAINHOOKS_BASE_URL.testnet,
+  apiKey: process.env.HIRO_API_KEY!,
+});
+
+const chainhook = await client.registerChainhook({
+  version: '1',
+  name: 'my-chainhook',
+  chain: 'stacks',
+  network: 'testnet',
+  filters: {
+    events: [
+      {
+        type: 'contract_call',
+        contract_identifier: 'SP...XYZ.counter',
+        function_name: 'increment',
+      },
+    ],
+  },
+  action: {
+    type: 'http_post',
+    url: 'https://example.com/webhooks',
+  },
+  options: {
+    decode_clarity_values: true,
+    enable_on_registration: true,
+  },
+});
+
+console.log('Chainhooks UUID:', chainhook.uuid);
+console.log('Enabled:', chainhook.status.enabled); // true
+```
+
+If you don't set `enable_on_registration`, the chainhook will be created but disabled by default.
+
+---
+
+## enableChainhook
+
+Enable or disable a single chainhook by UUID. This allows you to enable chainhooks after registration or pause without deleting it.
+
+### Examples
+
+```typescript
+// Enable a chainhook
+await client.enableChainhook('chainhook-uuid', true);
+
+// Disable a chainhook
+await client.enableChainhook('chainhook-uuid', false);
+```
+
+Returns HTTP `204 No Content` on success.
+
+---
+
+## bulkEnableChainhooks
+
+Enable or disable multiple chainhooks at once using filters. This is useful for managing many chainhooks programmatically.
+
+### By UUIDs
+
+Enable specific chainhooks by their UUIDs (maximum 200):
+
+```typescript
+await client.bulkEnableChainhooks({
+  enabled: true,
+  filters: {
+    uuids: [
+      'uuid-1',
+      'uuid-2',
+      'uuid-3',
+    ],
+  },
+});
+```
+
+### By Webhook URL
+
+Enable all chainhooks that POST to a specific URL:
+
+```typescript
+await client.bulkEnableChainhooks({
+  enabled: true,
+  filters: {
+    webhook_url: 'https://example.com/webhooks',
+  },
+});
+```
+
+### By Status
+
+Enable all chainhooks with a specific status:
+
+```typescript
+await client.bulkEnableChainhooks({
+  enabled: true,
+  filters: {
+    statuses: ['inactive'],
+  },
+});
+```
+
+### Combined Filters
+
+Use multiple filters together:
+
+```typescript
+await client.bulkEnableChainhooks({
+  enabled: false, // Disable matching chainhooks
+  filters: {
+    webhook_url: 'https://old-server.com/webhooks',
+    statuses: ['active'],
+  },
+});
+```
+
+This will disable all active chainhooks that POST to the old webhook URL.
+
+## Next steps
+
+- [Evaluate](evaluate.md): Test chainhooks against past blocks
+- [Filter Reference](reference/filters.md): Explore all filter options
diff --git a/docs/build/chainhooks/evaluate.md b/docs/build/chainhooks/evaluate.md
@@ -0,0 +1,71 @@
+---
+description: Replay any block height or hash against a chainhook to debug, backfill, or re-process historical events.
+---
+
+# Replay a block
+
+{% hint style="info" %}
+This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/tools/chainhooks/evaluate).
+{% endhint %}
+
+The evaluate endpoint replays any single block you choose—live or historical—against one of your registered chainhooks so you can validate filters without waiting for live traffic. Provide either a block height or block hash to target the exact block you care about.
+
+Use it to reproduce missed deliveries, inspect payload schemas after filter changes, or test webhook infrastructure with known blocks before enabling a hook in production.
+
+## evaluateChainhook
+
+### Evaluation Methods
+
+| Method | Parameter | Example |
+|--------|-----------|---------|
+| **By height** | `block_height` | `{ block_height: 100000 }` |
+| **By hash** | `index_block_hash` | `{ index_block_hash: '0xa204...' }` |
+
+### Example
+
+{% tabs %}
+{% tab title="with-block-height.ts" %}
+```ts
+import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client';
+
+const client = new ChainhooksClient({
+  baseUrl: CHAINHOOKS_BASE_URL.testnet,
+  apiKey: process.env.HIRO_API_KEY!,
+});
+
+await client.evaluateChainhook('chainhook-uuid', {
+  block_height: 100000,
+});
+```
+{% endtab %}
+
+{% tab title="with-block-hash.ts" %}
+```ts
+import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client';
+
+const client = new ChainhooksClient({
+  baseUrl: CHAINHOOKS_BASE_URL.testnet,
+  apiKey: process.env.HIRO_API_KEY!,
+});
+
+await client.evaluateChainhook('chainhook-uuid', {
+  index_block_hash: '0xa204...',
+});
+```
+{% endtab %}
+{% endtabs %}
+
+Returns HTTP `204 No Content`. If filters match, webhook payload is sent to your `action.url`.
+
+## Use Cases
+
+| Use Case | Description | Example |
+|----------|-------------|---------|
+| **Debug** | Investigate missed events | Replay a block height that should have triggered |
+| **Backfill** | Index historical data | Process older blocks created before the hook existed |
+| **Re-process** | Fix webhook handler issues | Re-evaluate a block after patching infrastructure |
+
+## Next steps
+
+- [Filter Reference](reference/filters.md): Configure which events to match
+- [Evaluate endpoint](https://docs.hiro.so/apis/chainhooks-api/reference/chainhooks/evaluate-chainhook): Replay past blocks through the API
diff --git a/docs/build/chainhooks/faq.md b/docs/build/chainhooks/faq.md
@@ -0,0 +1,127 @@
+---
+description: Frequently asked questions about Chainhooks 2.0 (Beta)
+---
+
+# FAQ
+
+{% hint style="info" %}
+This page is migrated from the [Hiro documentation](https://docs.hiro.so/en/tools/chainhooks/faq).
+{% endhint %}
+
+## Chainhooks 2.0 (Beta)
+
+<details>
+
+<summary>What is the goal/purpose of the Chainhooks 2.0 (Beta)?</summary>
+
+Our goal during the Beta is to learn as much as possible about the reliability, performance and developer experience of Chainhooks 2.0 in anticipation of the full release. If you encounter any issues, have any questions, or would like to share feedback during the Beta, please reach out to [beta@hiro.so](mailto:beta@hiro.so).
+
+</details>
+
+<details>
+
+<summary>Is the Chainhooks 2.0 (Beta) free?</summary>
+
+Yes! The Chainhooks 2.0 Beta is free for all participants.
+
+</details>
+
+<details>
+
+<summary>Will there be configuration or rate limits imposed during the Beta?</summary>
+
+All Beta users will initially be constrained to a limit of 10 Chainhooks configurations.
+
+</details>
+
+<details>
+
+<summary>How will Chainhooks be priced following the Beta?</summary>
+
+Chainhooks will be charged using a credit model for each delivery, with users able to select different credit limits depending on their usage. For Chainhooks 2.0 Beta users, your post-beta limits will initially be determined by your existing Hiro subscription tier.
+
+</details>
+
+## Version Management
+
+<details>
+
+<summary>What will happen to existing legacy Chainhooks running on v1.0?</summary>
+
+Users with Chainhooks running on v1.0 will still be able to view them and receive deliveries, but once the beta launches, all new Chainhooks created in the Platform will run on v2.0.
+
+The API will also not support Chainhooks running on v1.0.
+
+{% hint style="info" %}
+Learn how to migrate your v1 chainhooks to v2 in the [Migration Guide](migration.md).
+{% endhint %}
+
+</details>
+
+<details>
+
+<summary>If v2.0 and v1.0 will be live at the same time, how do we manage both?</summary>
+
+In the Platform, v1 chainhooks are read-only. You can view them and they will continue to deliver events, but you cannot modify them through the Platform UI.
+
+To modify v1 chainhooks programmatically, use the [Platform API](https://docs.hiro.so/apis/platform-api). However, we recommend migrating to v2 chainhooks instead. See the [Migration Guide](migration.md) for a complete walkthrough.
+
+</details>
+
+<details>
+
+<summary>How do I migrate my v1 chainhooks to v2?</summary>
+
+To migrate your v1 chainhooks to v2, follow the steps outlined in the [Migration Guide](migration.md).
+
+</details>
+
+## Platform vs SDK
+
+<details>
+
+<summary>Can I edit my v2 Chainhooks?</summary>
+
+Yes! you can edit your v2 Chainhooks using the [Chainhooks SDK](update.md) or [Chainhooks API](https://docs.hiro.so/apis/chainhooks-api). The Platform does not currently support editing v2 Chainhooks.
+
+</details>
+
+## Common Questions
+
+<details>
+
+<summary>Can I filter by multiple event types?</summary>
+
+Yes! See examples in the [Filter reference](reference/filters.md#combining-filters) guide for examples of combining filters.
+
+</details>
+
+<details>
+
+<summary>What happens if my webhook endpoint is down?</summary>
+
+Chainhooks will retry webhook deliveries and then "pause" your Chainhooks, giving you time to fix the issue and re-enable. Extended downtime may result in missed events, but you can use the [Evaluate](evaluate.md) feature to replay missed blocks.
+
+</details>
+
+<details>
+
+<summary>Can I test chainhooks locally?</summary>
+
+Currently, no. But we are working on a new feature that will help you quickly test chainhook payloads locally without requiring much setup.
+
+</details>
+
+---
+
+## Where to Get Help
+
+- **Discord**: Join the **#chainhook** channel on [Discord](https://stacks.chat/) under Hiro Developer Tools
+- **Email Support**: [beta@hiro.so](mailto:beta@hiro.so)
+
+---
+
+## Next Steps
+
+- [Create chainhooks](create.md): Register and enable chainhooks
+- [Payload anatomy](reference/payload-anatomy.md): Dive into the anatomy of a chainhook payload