Agent skill

Alchemy Webhooks Skill

Receive and verify Alchemy Notify webhooks. Use when setting up Alchemy webhook handlers, debugging X-Alchemy-Signature verification, or handling onchain events like ADDRESS_ACTIVITY, MINED_TRANSACTION, DROPPED_TRANSACTION, NFT_ACTIVITY, NFT_METADATA_UPDATE, or GRAPHQL (Custom Webhook).

Install this skill

npx skills add hookdeck/webhook-skills --skill alchemy-webhooks

When to Use This Skill

How do I receive Alchemy webhooks?
How do I verify Alchemy webhook signatures (the X-Alchemy-Signature header)?
How do I handle ADDRESS_ACTIVITY, MINED_TRANSACTION, or NFT_ACTIVITY events?
Why is my Alchemy webhook signature verification failing?
How do I set up Alchemy Notify webhooks for onchain activity?

Verification (core)

Alchemy signs every webhook with HMAC-SHA256 over the raw request body, hex-encoded, in the X-Alchemy-Signature header. There is no sha256= prefix and no timestamp — just the hex digest. The key is the per-webhook signing key (copied from the top-right of that webhook's detail page in the Notify dashboard, or fetched via the Notify API), not your app's Auth Token.

The alchemy-sdk npm package manages webhook CRUD but does not verify signatures — implement HMAC yourself. Always compute the HMAC over the raw body; a re-serialized JSON body will not match.

const crypto = require('crypto');

function verifyAlchemySignature(rawBody, signature, signingKey) {
  if (!signature) return false;
  const digest = crypto
    .createHmac('sha256', signingKey)
    .update(rawBody, 'utf8')   // rawBody: exact bytes/string received, never re-stringified JSON
    .digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(digest));
  } catch {
    return false; // length mismatch = invalid
  }
}

For complete handlers with route wiring, event dispatch, and tests, see:
examples/express/
examples/nextjs/
examples/fastapi/

Common Event Types

The webhook type field identifies the event. Alchemy webhooks are scoped per chain/network.

Type	Triggered When
`ADDRESS_ACTIVITY`	ETH/ERC-20/ERC-721/ERC-1155 transfers involving tracked addresses
`MINED_TRANSACTION`	A tracked transaction is mined into a block
`DROPPED_TRANSACTION`	A tracked transaction is dropped from the mempool
`NFT_ACTIVITY`	ERC-721/ERC-1155 transfers for tracked NFT contracts
`NFT_METADATA_UPDATE`	Metadata for a tracked NFT is refreshed
`GRAPHQL`	A Custom Webhook GraphQL query matches new onchain data

For full event and payload reference, see references/overview.md and the Alchemy Webhooks docs.

Environment Variables

ALCHEMY_SIGNING_KEY=whsec_or_your_per_webhook_signing_key   # top-right of the webhook's detail page
# Only needed for programmatic webhook CRUD via the Notify API / alchemy-sdk:
ALCHEMY_AUTH_TOKEN=your_app_auth_token                      # distinct from the signing key

Local Development

# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 alchemy --path /webhooks/alchemy

Configure the resulting URL as the webhook target in the Alchemy Notify dashboard. Optionally allowlist Alchemy's egress IPs: 54.236.136.17 and 34.237.24.169.

Reference Materials

references/overview.md - Alchemy webhook types, payloads, common events
references/setup.md - Dashboard + Notify API / alchemy-sdk configuration
references/verification.md - Signature verification details and gotchas