internet-court/internet-court-skill / vendored/quicknode/quicknode-skill
quicknode-skill
VerifiedQuicknode blockchain infrastructure for 80+ chains: Core RPC API, Streams, Webhooks, Blazar WSS, Solana gRPC, HyperCore gRPC, SQL Explorer, Metaplex DAS API, Blockbook, Ordinals & Runes API, Swap API, x402, MPP, Agent Subscriptions, CLI, and MCP. Use for any Quicknode product, blockchain data access, or wallet-paid agent access.
references/webhooks-reference.md
View on GitHub# Quicknode Webhooks Reference
Webhooks provide event-driven notifications for blockchain activity, delivering data to your HTTP endpoints in real-time.
## Webhooks vs Streams
| Feature | Webhooks | Streams |
|---------|----------|---------|
| **Complexity** | Simple setup | More configuration |
| **Filtering** | Template-based | Custom JavaScript |
| **Destinations** | HTTP only | Webhook, S3, Postgres, Azure |
| **Transformation** | Limited | Full transformation |
| **Best For** | Simple alerts | Complex data pipelines |
**Use Webhooks when:** You need simple, quick notifications for specific events.
**Use Streams when:** You need complex filtering, data transformation, or non-HTTP destinations.
> **Tip:** Need testnet tokens for webhook testing? Use the Quicknode faucet at https://faucet.quicknode.com/drip
## Creating Webhooks
### Via Dashboard
1. Navigate to Quicknode Dashboard → Webhooks
2. Click "Create Webhook"
3. Select network (Ethereum, Polygon, Solana, etc.)
4. Choose a webhook template and configure filters
5. Set destination URL
6. Test and activate
### Via API (Template-Based)
Webhooks are created from predefined templates using `POST /webhooks/rest/v1/webhooks/template/{templateId}`. Each template accepts a `templateArgs` object for configuration.
### Available Templates
| Template ID | Chain | Description |
|-------------|-------|-------------|
| `evmWalletFilter` | EVM | Monitor transactions to/from specific wallet addresses |
| `evmContractEvents` | EVM | Monitor events emitted by specific contracts |
| `evmAbiFilter` | EVM | Filter by ABI-decoded function calls or events |
| `solanaWalletFilter` | Solana | Monitor transactions involving Solana wallet addresses |
| `bitcoinWalletFilter` | Bitcoin | Monitor transactions involving Bitcoin addresses |
### Template Examples
**EVM Wallet Monitoring:**
```bash
curl -X POST https://api.quicknode.com/webhooks/rest/v1/webhooks/template/evmWalletFilter \
-H "Authorization: Bearer $QUICKNODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Wallet Monitor",
"network": "ethereum-mainnet",
"templateArgs": {
"addresses": ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]
},
"destination_url": "https://your-server.com/webhook",
"enabled": true
}'
```
**EVM Contract Events:**
```bash
curl -X POST https://api.quicknode.com/webhooks/rest/v1/webhooks/template/evmContractEvents \
-H "Authorization: Bearer $QUICKNODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "USDC Transfer Events",
"network": "ethereum-mainnet",
"templateArgs": {
"contracts": ["0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"],
"events": ["Transfer(address,address,uint256)"]
},
"destination_url": "https://your-server.com/webhook",
"enabled": true
}'
```
**EVM ABI Filter:**
```bash
curl -X POST https://api.quicknode.com/webhooks/rest/v1/webhooks/template/evmAbiFilter \
-H "Authorization: Bearer $QUICKNODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Uniswap Swaps",
"network": "ethereum-mainnet",
"templateArgs": {
"contracts": ["0x..."],
"abi": "[{\"type\":\"event\",\"name\":\"Swap\",...}]",
"events": ["Swap"]
},
"destination_url": "https://your-server.com/webhook",
"enabled": true
}'
```
**Solana Wallet Monitoring:**
```bash
curl -X POST https://api.quicknode.com/webhooks/rest/v1/webhooks/template/solanaWalletFilter \
-H "Authorization: Bearer $QUICKNODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Solana Wallet Monitor",
"network": "solana-mainnet",
"templateArgs": {
"addresses": ["YourSolanaWalletAddress..."]
},
"destination_url": "https://your-server.com/webhook",
"enabled": true
}'
```
**Bitcoin Wallet Monitoring:**
```bash
curl -X POST https://api.quicknode.com/webhooks/rest/v1/webhooks/template/bitcoinWalletFilter \
-H "Authorization: Bearer $QUICKNODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Bitcoin Wallet Monitor",
"network": "bitcoin-mainnet",
"templateArgs": {
"addresses": ["bc1q..."]
},
"destination_url": "https://your-server.com/webhook",
"enabled": true
}'
```
## Payload Format
### EVM Webhook Payload
```json
{
"webhookId": "webhook_abc123",
"network": "ethereum-mainnet",
"timestamp": 1693526400,
"blockNumber": 18000000,
"blockHash": "0x...",
"transactions": [
{
"hash": "0x...",
"from": "0x...",
"to": "0x...",
"value": "1000000000000000000",
"gas": "21000",
"gasPrice": "50000000000",
"input": "0x...",
"nonce": 42,
"logs": [
{
"address": "0x...",
"topics": [
"0xddf252ad...",
"0x000...from",
"0x000...to"
],
"data": "0x...",
"logIndex": 0
}
]
}
]
}
```
### Solana Webhook Payload
```json
{
"webhookId": "webhook_xyz789",
"network": "solana-mainnet",
"timestamp": 1693526400,
"slot": 200000000,
"transactions": [
{
"signature": "5K8Q...",
"meta": {
"fee": 5000,
"preBalances": [1000000000, 500000000],
"postBalances": [999995000, 500005000],
"err": null
},
"transaction": {
"message": {
"accountKeys": ["Account1...", "Account2..."],
"instructions": [
{
"programIdIndex": 0,
"accounts": [0, 1],
"data": "3Bxs..."
}
]
},
"signatures": ["5K8Q..."]
}
}
]
}
```
## Receiving Webhooks
### Express.js Server
```javascript
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());
// Verify webhook signature using all three security headers
function verifySignature(payload, signature, nonce, timestamp, secret) {
const expectedSig = crypto
.createHmac('sha256', secret)
.update(nonce + timestamp + JSON.stringify(payload))
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSig)
);
}
app.post('/webhook', (req, res) => {
const signature = req.headers['x-qn-signature'];
const nonce = req.headers['x-qn-nonce'];
const timestamp = req.headers['x-qn-timestamp'];
const secret = process.env.WEBHOOK_SECRET;
// Verify signature (includes nonce + timestamp to prevent replay attacks)
if (!verifySignature(req.body, signature, nonce, timestamp, secret)) {
return res.status(401).json({ error: 'Invalid signature' });
}
// Process webhook
const { network, transactions } = req.body;
for (const tx of transactions) {
console.log(`New transaction: ${tx.hash}`);
// Process transaction...
}
res.status(200).json({ received: true });
});
app.listen(3000);
```
### Python Flask Server
```python
from flask import Flask, request, jsonify
import hmac
import hashlib
import os
app = Flask(__name__)
def verify_signature(payload, signature, nonce, timestamp, secret):
expected = hmac.new(
secret.encode(),
(nonce + timestamp + payload).encode(),
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get('X-QN-Signature')
nonce = request.headers.get('X-QN-Nonce')
timestamp = request.headers.get('X-QN-Timestamp')
secret = os.environ.get('WEBHOOK_SECRET')
if not verify_signature(request.data.decode(), signature, nonce, timestamp, secret):
return jsonify({'error': 'Invalid signature'}), 401
data = request.json
for tx in data.get('transactions', []):
print(f"New transaction: {tx['hash']}")
# Process transaction...
return jsonify({'received': True}), 200
if __name__ == '__main__':
app.run(port=3000)
```
## Webhook Management API
### List Webhooks
```bash
curl https://api.quicknode.com/webhooks/rest/v1/webhooks \
-H "Authorization: Bearer $QUICKNODE_API_KEY"
```
### Get Webhook
```bash
curl https://api.quicknode.com/webhooks/rest/v1/webhooks/{webhookId} \
-H "Authorization: Bearer $QUICKNODE_API_KEY"
```
### Update Webhook
```bash
curl -X PATCH https://api.quicknode.com/webhooks/rest/v1/webhooks/{webhookId} \
-H "Authorization: Bearer $QUICKNODE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": false
}'
```
### Delete Webhook
```bash
curl -X DELETE https://api.quicknode.com/webhooks/rest/v1/webhooks/{webhookId} \
-H "Authorization: Bearer $QUICKNODE_API_KEY"
```
### Test Webhook
```bash
curl -X POST https://api.quicknode.com/webhooks/rest/v1/webhooks/{webhookId}/test \
-H "Authorization: Bearer $QUICKNODE_API_KEY"
```
## Security Best Practices
1. **Verify signatures** - Always validate using all three headers: `X-QN-Signature`, `X-QN-Nonce`, and `X-QN-Timestamp`
2. **Use HTTPS** - Never use HTTP endpoints for webhooks
3. **Timeout handling** - Respond within 30 seconds
4. **Idempotency** - Handle duplicate deliveries gracefully
5. **Error handling** - Return proper HTTP status codes
6. **Rate limiting** - Implement rate limiting on your endpoint
## Retry Policy
Quicknode automatically retries failed webhook deliveries:
| Attempt | Delay |
|---------|-------|
| 1 | Immediate |
| 2 | 1 minute |
| 3 | 5 minutes |
| 4 | 30 minutes |
| 5 | 2 hours |
After 5 failed attempts, the webhook is marked as failed. Check the dashboard for delivery status.
## Common Use Cases
### Transaction Alerts (Wallet Monitoring)
Use the `evmWalletFilter` template with your wallet address to get notified of all incoming and outgoing transactions. For Solana, use `solanaWalletFilter`; for Bitcoin, use `bitcoinWalletFilter`.
### NFT Sales Monitoring
Use the `evmContractEvents` template with the marketplace contract address and the sale/transfer event signature to monitor NFT sales in real-time.
### Token Transfers
Use the `evmContractEvents` template with the token contract address and the `Transfer(address,address,uint256)` event to track all transfers for a specific ERC-20 or ERC-721 token.
### DeFi Activity
Use the `evmAbiFilter` template with the DEX contract address and the relevant ABI (e.g., `Swap` event) to monitor swaps, liquidity changes, and other DeFi activity.
### Smart Contract Monitoring
Use the `evmContractEvents` or `evmAbiFilter` template with a contract address to monitor all events emitted by a specific smart contract. Track state changes, admin actions, upgrades, or any on-chain activity tied to the contract.
### Wallet Monitoring
Use chain-specific wallet filters (`evmWalletFilter`, `solanaWalletFilter`, `bitcoinWalletFilter`) to track all activity for a specific wallet address, including incoming/outgoing transfers, token approvals, and contract interactions.
### Account Monitoring
Use webhooks to monitor specific accounts across chains. On Solana, track account data changes with `solanaAccountFilter`. On EVM chains, combine `evmWalletFilter` with `evmContractEvents` to get a complete view of an account's on-chain activity, including balance changes, token movements, and contract interactions.
## Troubleshooting
| Issue | Cause | Solution |
|-------|-------|----------|
| No deliveries | Template filters too narrow | Broaden template filters (add more addresses, use broader event signatures) |
| 401 errors | Invalid signature | Check secret configuration |
| Timeouts | Slow processing | Optimize handler, use async |
| Missing data | Incomplete template config | Add required addresses, events, or contract parameters |
| Duplicates | Retry deliveries | Implement idempotency |
## Documentation
- **Webhooks Overview**: https://www.quicknode.com/docs/webhooks
- **Webhooks Overview (llms.txt)**: https://www.quicknode.com/docs/webhooks/llms.txt
- **Webhook Templates API**: https://www.quicknode.com/docs/webhooks/rest-api/webhooks/webhooks-rest-create-from-template
- **API Reference**: https://www.quicknode.com/docs/webhooks/rest-api/getting-started
- **Guides**: https://www.quicknode.com/guides/tags/webhooks
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 195k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| paperclip-pagepaperclipai/paperclipPublish static HTML pages and asset folders to the Paperclip S3/CloudFront page host. Use when asked to deploy, host, or share a persistent page, viewer, prototype, report, or static site without here.now. | Stars: 114k | Updated | Claude CodeCodex | Verified | Install |
| verify-paperclippaperclipai/paperclipVerify Paperclip from a source checkout, published npm install, or existing staging or production stack. Select the environment, data state, version, and platform; drive real UI or CLI journeys and capture evidence. Route deployment to the private Cloud skills. | Stars: 114k | Updated | Claude CodeCodex | Verified | Install |