Webhooks

Receba callbacks HTTP POST de provedores RPC quando contas ou transações correspondem aos seus filtros - indexação orientada a eventos sem manter clientes WebSocket ou gRPC.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

# Dashboard do provedor: criar webhook
# URL: https://api.yourapp.com/webhooks/helius
# Tipo: enhanced transaction / account / raw
# Endereços de conta: YOUR_PROGRAM_ID

// Handler de rota Next.js (ilustrativo)
export async function POST(req: Request) {
  const body = await req.json();
  // verifique header de auth / assinatura conforme docs do provedor
  await enqueueForIndexer(body);
  return new Response("ok");
}

Quando usar isso:

• Serverless ou equipe pequena sem consumidores gRPC.
• Reagir a transações específicas de programa em quase tempo real.
• Disparar workflows (e-mails, alertas) em eventos on-chain.
• Complementar análises em lote com notificações ao vivo.

Exemplo de Trabalho

import { createHmac, timingSafeEqual } from "node:crypto";
 
function verifyHeliusSignature(
  secret: string,
  payload: string,
  header: string | null
): boolean {
  if (!header) return false;
  const expected = createHmac("sha256", secret).update(payload).digest("hex");
  try {
    return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
  } catch {
    return false;
  }
}
 
export async function POST(req: Request) {
  const raw = await req.text();
  const sig = req.headers.get("x-helius-signature");
  if (!verifyHeliusSignature(process.env.HELIUS_WEBHOOK_SECRET!, raw, sig)) {
    return new Response("unauthorized", { status: 401 });
  }
  const event = JSON.parse(raw);
  await persistTransactionEvent(event);
  return Response.json({ received: true });
}

O que isso demonstra:

• Verifique autenticidade do webhook antes de analisar JSON.
• Responda 200 rapidamente; indexação pesada assíncrona via fila.
• Armazene payload bruto para debug de replay.

Deep Dive

Como Funciona

• O indexador do provedor combina eventos da chain com os filtros registrados.
• HTTP POST entrega payload JSON no seu endpoint HTTPS.
• Retentativas em respostas não-2xx - handlers idempotentes são obrigatórios.
• Payloads enhanced podem incluir transferências de token analisadas e metadados NFT.

Design de Webhook

Notas TypeScript

// Padrão ACK rápido com fila
await queue.add("index-tx", { id: event.signature });
return Response.json({ ok: true });

Armadilhas

• Sem verificação de assinatura - atacantes enviam eventos falsos. Correção: HMAC ou token de auth do provedor em toda requisição.
• Handler lento causa tempestade de retentativas - processamento duplicado. Correção: worker de fila + upserts idempotentes.
• HTTP público sem TLS - credenciais e dados expostos. Correção: apenas HTTPS.
• Filtro muito amplo - spam de webhook e custo. Correção: restrinja a program id e tipos de instrução.
• Tratar webhooks como única fonte da verdade - eventos perdidos em downtime. Correção: job periódico de reconciliação RPC backfill.

Alternativas

FAQs

Relacionado

• Noções Básicas de Indexação - contexto do pipeline
• Construindo um Indexador - persistência
• Provedores RPC - configuração Helius
• Analisando Dados de Programa - decodificar payloads

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.