Register Chainhooks on devnet

Learn how to register Chainhooks on devnet to monitor and react to smart contract events during local development.

What you'll learn

In this guide, you'll learn how to register Chainhooks on devnet to monitor and react to smart contract events during local development.

Creating Chainhook predicate files for event monitoring

Registering Chainhooks with Clarinet devnet

Monitoring contract calls and blockchain events

Setting up webhooks for real-time notifications

Prerequisites

To follow this guide, you'll need:

Clarinet version 2.1.0 or higher required. Check with clarinet --version.

Quickstart

Create your Chainhook predicates

Create Chainhook predicate files in your project root or a dedicated folder:

counter.clar

increment.json

decrement.json

Clarinet.toml

Example predicate for monitoring increment events:

chainhooks/increment.json

{
  "chain": "stacks",
  "uuid": "increment-hook",
  "name": "Increment Counter Hook",
  "version": 1,
  "networks": {
    "devnet": {
      "if_this": {
        "scope": "contract_call",
        "contract_identifier": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.counter",
        "method": "increment"
      },
      "then_that": {
        "http_post": {
          "url": "http://localhost:3000/api/increment",
          "authorization_header": "Bearer my-secret"
        }
      }
    }
  }
}

Start devnet with Chainhooks

Start devnet from your project root. Clarinet automatically registers all Chainhook files:

Terminal

$ clarinet devnet start

Look for the registration confirmation:

Terminal

$ clarinet devnet start
# ...
INFO Feb  5 15:20:07.233382 2 chainhooks registered

Monitor Chainhook activity

When contract actions occur, you'll see Chainhook triggers in the terminal:

Terminal

$ clarinet devnet start
# ...
INFO Feb  5 15:21:07.233382 1 hooks triggered

Verify the payload based on your then_that configuration:

http_post - Check your endpoint received the POST request
file_append - Verify the file was created/updated

Common patterns

Contract deployment hook

Monitor when specific contracts are deployed:

chainhooks/deploy-monitor.json

{
  "chain": "stacks",
  "uuid": "deploy-hook",
  "name": "Contract Deploy Monitor",
  "version": 1,
  "networks": {
    "devnet": {
      "if_this": {
        "scope": "contract_deployment",
        "deployer": "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM"
      },
      "then_that": {
        "file_append": {
          "path": "./deployments.log"
        }
      }
    }
  }
}

STX transfer monitoring

Track STX transfers above a certain threshold:

chainhooks/stx-transfers.json

{
  "chain": "stacks",
  "uuid": "stx-transfer-hook",
  "name": "Large STX Transfer Monitor",
  "version": 1,
  "networks": {
    "devnet": {
      "if_this": {
        "scope": "stx_event",
        "actions": ["transfer"],
        "amount_upper_bound": "1000000000000"
      },
      "then_that": {
        "http_post": {
          "url": "http://localhost:3000/api/large-transfer"
        }
      }
    }
  }
}

Next steps

Learn about Chainhook scopes and predicates
Set up Stacks.js integration for frontend interaction
Explore CI/CD workflows for automated testing