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.

Example

1import { ChainhooksClient, CHAINHOOKS_BASE_URL } from '@hirosystems/chainhooks-client';
2
3const client = new ChainhooksClient({
4  baseUrl: CHAINHOOKS_BASE_URL.testnet,
5  apiKey: process.env.HIRO_API_KEY!,
6});
7
8const chainhook = await client.registerChainhook({
9  version: '1',
10  name: 'my-chainhook',
11  chain: 'stacks',
12  network: 'testnet',
13  filters: {
14    events: [
15      {
16        type: 'contract_call',
17        contract_identifier: 'SP...XYZ.counter',
18        function_name: 'increment',
19      },
20    ],
21  },
22  action: {
23    type: 'http_post',
24    url: 'https://example.com/webhooks',
25  },
26  options: {
27    decode_clarity_values: true,
28    enable_on_registration: true,
29  },
30});
31
32console.log('Chainhook UUID:', chainhook.uuid);
33console.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

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

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.

Evaluate→

Test chainhooks against past blocks

Filter Reference→

Explore all filter options

Create chainhooks