Webhooks

Recibe callbacks HTTP POST de los proveedores RPC cuando las cuentas o transacciones coincidan con tus filtros: indexación basada en eventos sin mantener clientes WebSocket o gRPC.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

# Panel del proveedor: crear webhook
# URL: https://api.yourapp.com/webhooks/helius
# Tipo: transacción mejorada / cuenta / cruda
# Direcciones de cuenta: YOUR_PROGRAM_ID

// Manejador de ruta de Next.js (ilustrativo)
export async function POST(req: Request) {
  const body = await req.json();
  // verificar la cabecera de autenticación / firma según la documentación del proveedor
  await enqueueForIndexer(body);
  return new Response("ok");
}

Cuándo usar esto:

• Entornos sin servidor o equipos pequeños sin consumidores gRPC.
• Reaccionar a transacciones específicas del programa en tiempo casi real.
• Desencadenar flujos de trabajo (correos electrónicos, alertas) ante eventos en la cadena.
• Complementar el análisis por lotes con notificaciones en vivo.

Ejemplo de trabajo

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 });
}

Lo que esto demuestra:

• Verificar la autenticidad del webhook antes de analizar el JSON.
• Responder 200 rápidamente; indexación pesada asíncrona a través de una cola.
• Almacenar la carga útil cruda para depuración de repetición.

Inmersión Profunda

Cómo funciona

• El indexador del proveedor coincide con los eventos de la cadena con tus filtros registrados.
• HTTP POST entrega la carga útil JSON a tu punto final HTTPS.
• Reintentos ante respuestas no 2xx: se requieren manejadores idempotentes.
• Las cargas útiles mejoradas pueden incluir transferencias de tokens analizadas y metadatos NFT.

Diseño de Webhook

Notas de TypeScript

// Patrón ACK rápido con cola
await queue.add("index-tx", { id: event.signature });
return Response.json({ ok: true });

Trampas

• Sin verificación de firma - los atacantes envían eventos falsos. Solución: HMAC o token de autenticación del proveedor en cada solicitud.
• Manejador lento causa tormentas de reintentos - procesamiento duplicado. Solución: trabajador de cola + inserciones idempotentes.
• HTTP público sin TLS - credenciales y datos expuestos. Solución: solo HTTPS.
• Filtro demasiado amplio - spam de webhook y costo. Solución: limitar al ID del programa y tipos de instrucción.
• Tratar los webhooks como única fuente de verdad - eventos perdidos durante el tiempo de inactividad. Solución: trabajo de reconciliación de backfill RPC periódico.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de indexación - contexto del pipeline
• Construcción de un indexador - persistencia
• Proveedores RPC - configuración de Helius
• Análisis de datos de programas - decodificación de cargas útiles

Versiones de la pila: Esta página se escribió 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 y LiteSVM 0.6.x.