Get a signed webhook when a Bitcoin address receives or spends BTC. Chainhook waits 6 confirmations, about 1 hour, so every event is for a settled payment.
The contract Chainhook watches, how amounts are scaled, and how long BTC takes to reach your endpoint.
Watching Bitcoin addresses yourself means running Bitcoin Core with an index, or polling an explorer API per address and handling blocks that get replaced. Chainhook reads each block, waits 6 confirmations, and posts each matching output or spend to your endpoint.
Create a webhook with network: "bitcoin", type: "native" and the address you want to watch. The signing secret is returned once.
Every Bitcoin block is scanned. A matching BTC transfer is held until it is 6 blocks deep, about 1 hour.
A transfer.detected event arrives with an X-Webhook-Signature header. Failed attempts are retried automatically, up to 3 attempts in total, waiting 1 minute, then 5 minutes between attempts.
{
"network": "bitcoin",
"type": "native",
"direction": "in",
"address": "bc1qv2vpdy2x85y2srpthhacwx3eep3xh85jej7y6c",
"webhook_url": "https://api.example.com/webhooks/chainhook"
}What your endpoint receives for an incoming BTC transfer on Bitcoin. amount is already scaled by decimals; amount_raw is the on-chain integer.
POST /webhooks/chainhook HTTP/1.1 Host: api.example.com Content-Type: application/json User-Agent: chainhook/1.x X-Webhook-Id: 01a0fbfd-4fe4-7a3c-8f21-6b9d0e4c7a15 X-Webhook-Signature: 7a12d02673420517279805cf8188a1a62c6f69706161ba5cf0a8ec91ea66b8e3 { "id": "01a0fbfd-4fe4-7a3c-8f21-6b9d0e4c7a15", "event": "transfer.detected", "created_at": "2026-10-02T09:41:17Z", "webhook_id": "01a0fbf2-fadc-7c3e-9b1a-4d6f2e8a5c71", "data": { "network": "bitcoin", "direction": "in", "type": "native", "transaction_hash": "7bfdb19491c0fd391e9aa2fbbf061fd86d7d739636771cfa340049c34ae38bb7", "transfer_index": 1, "block_number": 972429, "block_hash": "00000000000000000001a6f4c2e9b07d3a5f81c6e4b2d9a7f03c5e8b1d4a6f29", "block_timestamp": "2026-10-02T09:41:05Z", "confirmations": 6, "from": null, "to": "bc1qv2vpdy2x85y2srpthhacwx3eep3xh85jej7y6c", "currency": "BTC", "amount": "0.015", "amount_raw": "1500000", "decimals": 8, "contract_address": null } }
X-Webhook-Signature is a hex HMAC-SHA256 of the raw body, keyed with your webhook's secret. Reject any request where it doesn't match.
import crypto from 'node:crypto'; import express from 'express'; const app = express(); app.post( '/webhooks/chainhook', express.raw({ type: 'application/json' }), (req, res) => { const signature = req.get('X-Webhook-Signature') ?? ''; const expected = crypto .createHmac('sha256', process.env.CHAINHOOK_SIGNING_SECRET) .update(req.body) .digest('hex'); const valid = signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)); if (!valid) { return res.sendStatus(401); } const event = JSON.parse(req.body); // Skip event.id if you've already processed it. res.sendStatus(200); }, );
If a transaction pays your address in two outputs, you get two events, each with its own transfer_index (the output number). Incoming events have from: null, because a Bitcoin transaction can be funded by many addresses.
An outgoing event reports the total of the inputs your address spent, with to: null. Change sent back to the same address shows up as a separate incoming event, so net the two if you track balances.
amount is in BTC and amount_raw in satoshis (8 decimals). 0.015 BTC is an amount_raw of 1500000.
Store the event id, or transaction_hash with transfer_index, and skip duplicates. Delivery is at least once.
Start with 100 trial detections for 1 month and pay only for what you use. Paid plans add detections, webhooks, and per-detection overage.
$0/month
Card required, no monthly fee
$9/month
or $90/year billed yearly
$29/month
or $290/year billed yearly
$99/month
or $990/year billed yearly
Custom limits for teams that need more than 400,000 detections a month or more than 200 active webhooks. Contact us and we'll set up a plan around your volume.
Prices in USD, plus applicable tax. Billed monthly or yearly, and paid allowances reset monthly. Cancel any time and keep your plan until the period ends.
Can't find your answer? Contact support.
Create a webhook with network: "bitcoin", type: "native", direction: "in" and the receiving address. Each confirmed output paid to it arrives as a transfer.detected event.
Chainhook waits 6 confirmations, and Bitcoin averages a block every 10 minutes. Unconfirmed transactions can be replaced, so they are never reported.
Incoming events leave from empty because a transaction can have many inputs. Look up the transaction_hash on a block explorer if you need the inputs.
Create an account and start with 100 trial detections for 1 month.
