Register & Enable

Learn how to create and activate chainhooks using the Chainhook SDK.

registerChainhook

Creates a new chainhook configuration. By default, new chainhooks are created in a disabled state unless enable_on_registration is set to true.

TypeScript

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, // Enable immediately
  },
});

console.log('Chainhook UUID:', chainhook.uuid);
console.log('Enabled:', chainhook.status.enabled); // true

cURL

curl -sS -X POST "https://api.testnet.hiro.so/chainhooks/me" \
  -H "content-type: application/json" \
  -H "x-api-key: $HIRO_API_KEY" \
  -d '{
    "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
    }
  }'

Response

{
  "uuid": "be4ab3ed-b606-4fe0-97c4-6c0b1ac9b185",
  "definition": {
    "version": "1",
    "name": "my-chainhook",
    "chain": "stacks",
    "network": "testnet",
    "filters": { ... },
    "action": { ... },
    "options": { ... }
  },
  "status": {
    "enabled": true,
    "type": "active"
  }
}

Enable Later

If you don't set enable_on_registration, the chainhook will be created but disabled:

const chainhook = await client.registerChainhook({
  version: '1',
  name: 'my-chainhook',
  chain: 'stacks',
  network: 'testnet',
  filters: { /* ... */ },
  action: { /* ... */ },
  // No options.enable_on_registration
});

console.log('Enabled:', chainhook.status.enabled); // false

// Enable it later
await client.enableChainhook(chainhook.uuid, true);

enableChainhook

Enable or disable a single chainhook by UUID. This allows you to pause a chainhook without deleting it.

TypeScript

// Enable a chainhook
await client.enableChainhook('chainhook-uuid', true);

// Disable a chainhook
await client.enableChainhook('chainhook-uuid', false);

cURL

Enable:

curl -sS -X PATCH "https://api.testnet.hiro.so/chainhooks/me/<chainhook-uuid>/enabled" \
  -H "content-type: application/json" \
  -H "x-api-key: $HIRO_API_KEY" \
  -d '{ "enabled": true }'

Disable:

curl -sS -X PATCH "https://api.testnet.hiro.so/chainhooks/me/<chainhook-uuid>/enabled" \
  -H "content-type: application/json" \
  -H "x-api-key: $HIRO_API_KEY" \
  -d '{ "enabled": false }'

Response

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):

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:

await client.bulkEnableChainhooks({
  enabled: true,
  filters: {
    webhook_url: 'https://example.com/webhooks',
  },
});

By Status

Enable all chainhooks with a specific status:

await client.bulkEnableChainhooks({
  enabled: true,
  filters: {
    statuses: ['inactive'],
  },
});

Combined Filters

Use multiple filters together:

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.

cURL

curl -sS -X PATCH "https://api.testnet.hiro.so/chainhooks/me/enabled" \
  -H "content-type: application/json" \
  -H "x-api-key: $HIRO_API_KEY" \
  -d '{
    "enabled": true,
    "filters": {
      "uuids": ["uuid-1", "uuid-2"],
      "webhook_url": "https://example.com/webhooks"
    }
  }'

Response

{
  "updated": 5,
  "results": [
    {
      "uuid": "uuid-1",
      "enabled": true
    },
    {
      "uuid": "uuid-2",
      "enabled": true
    }
  ]
}

Evaluate→

Test chainhooks against past blocks

Filter Reference→

Explore all filter options

Register & Enable

Evaluate→

Filter Reference→

How is this guide?