Register Chainhooks on devnet

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

What you'll learn

Create Chainhook predicate files for event monitoring

Monitor contract calls and blockchain events

Set up webhooks for real-time notifications

Prerequisites

Clarinet version 2.1.0 or higher required. Check with clarinet --version.
Node.js version 16 or higher required. Check with node --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"
        }
      }
    }
  }
}