Create chainhooks

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

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('Chainhooks 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

1// Enable a chainhook
2await client.enableChainhook('chainhook-uuid', true);
3
4// Disable a chainhook
5await 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):

1await client.bulkEnableChainhooks({
2  enabled: true,
3  filters: {
4    uuids: [
5      'uuid-1',
6      'uuid-2',
7      'uuid-3',
8    ],
9  },
10});

By Webhook URL

Enable all chainhooks that POST to a specific URL:

1await client.bulkEnableChainhooks({
2  enabled: true,
3  filters: {
4    webhook_url: 'https://example.com/webhooks',
5  },
6});

By Status

Enable all chainhooks with a specific status:

1
2await client.bulkEnableChainhooks({
3  enabled: true,
4  filters: {
5    statuses: ['inactive'],
6  },
7});

Combined Filters

Use multiple filters together:

1await client.bulkEnableChainhooks({
2  enabled: false, // Disable matching chainhooks
3  filters: {
4    webhook_url: 'https://old-server.com/webhooks',
5    statuses: ['active'],
6  },
7});

This will disable all active chainhooks that POST to the old webhook URL.

Next steps

Evaluate→

Test chainhooks against past blocks

Filter Reference→

Explore all filter options

Create chainhooks

Evaluate→

Filter Reference→

How is this guide?