Webhook Management

/**
 * Get all webhooks for the current API key
 * @returns Promise resolving to array of webhooks
 */
getAllWebhooks(): Promise<Webhook[]>;

/**
 * Get a specific webhook by ID
 * @param webhookId - Webhook ID to retrieve
 * @returns Promise resolving to webhook details
 */
getWebhook(webhookId: string): Promise<Webhook>;

/**
 * Create a new webhook
 * @param params - Webhook configuration parameters
 * @returns Promise resolving to created webhook
 */
createWebhook(params: WebhookParams): Promise<Webhook>;

/**
 * Update an existing webhook
 * @param webhookId - Webhook ID to update
 * @param params - Updated webhook parameters
 * @returns Promise resolving to void
 */
updateWebhook(webhookId: string, params: WebhookParams): Promise<void>;

/**
 * Delete a webhook
 * @param webhookId - Webhook ID to delete
 * @returns Promise resolving to void
 */
deleteWebhook(webhookId: string): Promise<void>;

interface Webhook {
  id: string;
  network: Network;
  type: WebhookType;
  url: string;
  isActive: boolean;
  timeCreated: string;
  signingKey: string;
  version: WebhookVersion;
  appId?: string;
}

interface WebhookParams {
  type: WebhookType;
  url: string;
  addresses?: string[];
  network?: Network;
  appId?: string;
}

enum WebhookType {
  ADDRESS_ACTIVITY = "ADDRESS_ACTIVITY",
  MINED_TRANSACTION = "MINED_TRANSACTION", 
  DROPPED_TRANSACTION = "DROPPED_TRANSACTION",
  GRAPHQL = "GRAPHQL",
  NFT_ACTIVITY = "NFT_ACTIVITY",
  NFT_METADATA_UPDATE = "NFT_METADATA_UPDATE",
}

enum WebhookVersion {
  V1 = "V1",
  V2 = "V2",
}

/**
 * Get addresses tracked by a webhook
 * @param webhookId - Webhook ID to get addresses for
 * @returns Promise resolving to array of tracked addresses
 */
getAddresses(webhookId: string): Promise<string[]>;

/**
 * Add addresses to track for a webhook
 * @param webhookId - Webhook ID to add addresses to
 * @param addresses - Array of addresses to start tracking
 * @returns Promise resolving to void
 */
addAddresses(webhookId: string, addresses: string[]): Promise<void>;

/**
 * Remove addresses from webhook tracking
 * @param webhookId - Webhook ID to remove addresses from
 * @param addresses - Array of addresses to stop tracking
 * @returns Promise resolving to void
 */
removeAddresses(webhookId: string, addresses: string[]): Promise<void>;

/**
 * Replace all tracked addresses for a webhook
 * @param webhookId - Webhook ID to update addresses for
 * @param addresses - New array of addresses to track
 * @returns Promise resolving to void
 */
updateAddresses(webhookId: string, addresses: string[]): Promise<void>;

interface AddressActivityWebhook extends Webhook {
  type: WebhookType.ADDRESS_ACTIVITY;
  addresses: string[];
}

interface MinedTransactionWebhook extends Webhook {
  type: WebhookType.MINED_TRANSACTION;
  addresses: string[];
  includeRemoved?: boolean;
  hashesOnly?: boolean;
}

interface DroppedTransactionWebhook extends Webhook {
  type: WebhookType.DROPPED_TRANSACTION;
  addresses: string[];
  includeRemoved?: boolean;
  hashesOnly?: boolean;
}

interface NftActivityWebhook extends Webhook {
  type: WebhookType.NFT_ACTIVITY;
  filters: NftFilter[];
}

interface NftMetadataUpdateWebhook extends Webhook {
  type: WebhookType.NFT_METADATA_UPDATE;
  filters: NftFilter[];
}

interface GraphqlWebhook extends Webhook {
  type: WebhookType.GRAPHQL;
  graphqlQuery: string;
}

interface NftFilter {
  contractAddress?: string;
  tokenId?: string;
}

interface WebhookEvent {
  webhookId: string;
  id: string;
  createdAt: string;
  type: WebhookType;
  event: AddressActivityEvent | MinedTransactionEvent | DroppedTransactionEvent | NftActivityEvent;
}

interface AddressActivityEvent {
  network: Network;
  activity: AddressActivity[];
}

interface AddressActivity {
  fromAddress: string;
  toAddress: string;
  blockNum: string;
  hash: string;
  value: number;
  erc721TokenId?: string;
  erc1155Metadata?: Erc1155Metadata[];
  asset: string;
  category: AssetTransfersCategory;
  rawContract: RawContract;
}

interface MinedTransactionEvent {
  app: string;
  network: Network;
  fullTransaction: TransactionResponse;
}

interface DroppedTransactionEvent {
  app: string;
  network: Network;
  hash: string;
  from: string;
  to: string;
  value: string;
}

interface NftActivityEvent {
  network: Network;
  activity: NftActivity[];
}

interface NftActivity {
  contractAddress: string;
  tokenId: string;
  fromAddress: string;
  toAddress: string;
  transactionHash: string;
  blockNumber: number;
  category: NftActivityType;
}

enum NftActivityType {
  TRANSFER = "transfer",
  MINT = "mint",
  BURN = "burn",
  SALE = "sale",
}

/**
 * Verify webhook signature to ensure authenticity
 * @param body - Raw webhook payload body
 * @param signature - Webhook signature from headers
 * @param signingKey - Webhook signing key
 * @returns Boolean indicating if signature is valid
 */
function verifyWebhookSignature(
  body: string,
  signature: string,
  signingKey: string
): boolean;

/**
 * Get webhook signing key for signature verification
 * @param webhookId - Webhook ID to get signing key for
 * @returns Promise resolving to signing key
 */
getWebhookSigningKey(webhookId: string): Promise<string>;

/**
 * Regenerate webhook signing key
 * @param webhookId - Webhook ID to regenerate key for
 * @returns Promise resolving to new signing key
 */
regenerateWebhookSigningKey(webhookId: string): Promise<string>;

import { Alchemy, Network, WebhookType } from "alchemy-sdk";

const alchemy = new Alchemy({
  apiKey: "your-api-key",
  network: Network.ETH_MAINNET,
});

// Create address activity webhook
const webhook = await alchemy.notify.createWebhook({
  type: WebhookType.ADDRESS_ACTIVITY,
  url: "https://your-server.com/webhook",
  addresses: ["0x...", "0x..."],
});

// Get all webhooks
const allWebhooks = await alchemy.notify.getAllWebhooks();

// Add more addresses to track
await alchemy.notify.addAddresses(webhook.id, [
  "0x...", // new address to track
]);

// Create NFT activity webhook
const nftWebhook = await alchemy.notify.createWebhook({
  type: WebhookType.NFT_ACTIVITY,
  url: "https://your-server.com/nft-webhook", 
  filters: [
    { contractAddress: "0x..." }, // specific collection
  ],
});

// Create mined transaction webhook
const minedWebhook = await alchemy.notify.createWebhook({
  type: WebhookType.MINED_TRANSACTION,
  url: "https://your-server.com/mined",
  addresses: ["0x..."],
});

// Verify webhook signature (in your webhook handler)
function handleWebhook(req, res) {
  const signature = req.headers['x-alchemy-signature'];
  const body = JSON.stringify(req.body);
  const signingKey = webhook.signingKey;
  
  const isValid = verifyWebhookSignature(body, signature, signingKey);
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }
  
  // Process webhook payload
  const webhookData = req.body;
  console.log('Received webhook:', webhookData);
  
  res.status(200).send('OK');
}

// Update webhook URL
await alchemy.notify.updateWebhook(webhook.id, {
  type: WebhookType.ADDRESS_ACTIVITY,
  url: "https://new-server.com/webhook",
  addresses: ["0x..."],
});

// Delete webhook when no longer needed
await alchemy.notify.deleteWebhook(webhook.id);