Webhooks de Polygon: Obtenga eventos on-chain en tiempo real sin sondeo

Los webhooks de Polygon son devoluciones de llamada HTTP que un servicio envía a su servidor cuando ocurre algo en la cadena de Polygon, como un depósito de USDC que llega a una de sus direcciones. Usted registra una URL, el proveedor vigila la cadena y su backend recibe una solicitud POST firmada en lugar de golpear un nodo RPC cada pocos segundos. Esta guía explica cómo funciona eso en Polygon PoS, qué puede salir mal y cómo construir un manejador en el que pueda confiar con dinero.

TL;DR

• Un webhook sustituye al sondeo: el proveedor vigila Polygon y envía eventos (depósitos, transferencias, movimientos de tokens) a su endpoint.
• Los bloques de Polygon llegan aproximadamente cada 2 segundos, por lo que los eventos son rápidos, pero aún necesita una política de confirmaciones antes de acreditar fondos.
• Trate cada entrega como posiblemente duplicada, tardía o fuera de orden: verifique la firma, almacene el ID del evento y procese de forma idempotente.
• Acuse recibo rápido, haga el trabajo en una cola y concilie contra la cadena según un calendario.
• Los Webhooks de Chaingateway entregan eventos de Polygon predecodificados y firmados con HMAC, así que se ahorra ejecutar nodos y analizar logs.

Tabla de contenidos

• Qué es realmente un webhook de Polygon
• Por qué los webhooks superan al sondeo en Polygon
• Confirmaciones, finalidad y reorganizaciones en Polygon PoS
• Aspecto de un manejador de webhooks de Polygon seguro
• Tokens y casos límite en Polygon
• Construirlo usted mismo o usar una API unificada
• Nuestra perspectiva: los webhooks son un problema de libro mayor, no de notificación
• Obtener webhooks de Polygon con Chaingateway
• Lista de comprobación para el lanzamiento
• Preguntas frecuentes
• Fuentes

Qué es realmente un webhook de Polygon

Polygon PoS es una cadena EVM. Cada transferencia ERC-20, ya sea USDC, USDT o un token que usted haya emitido, emite un log Transfer. El POL nativo se mueve como una transferencia de valor simple sin ningún log. El RPC en bruto le da ambos en formas diferentes: logs para tokens, datos de transacción y trazas para monedas nativas. Si quiere saber que un cliente pagó, tiene que componer esa imagen usted mismo.

Un servicio de webhooks hace el montaje. Usted se suscribe a una dirección (o a un conjunto de ellas) y, cuando ocurre un evento coincidente, el servicio envía una carga útil JSON a su URL. Una buena carga útil le indica la cadena, el hash de la transacción, remitente, destinatario, token, cantidad en unidades humanas, número de bloque y un identificador de evento único. Esa es la diferencia entre “aquí hay un log con temas en hexadecimal” y “el cliente 4812 pagó 250 USDC”.

Realmente hay tres herramientas diferentes que la gente busca bajo esta palabra clave:

• Webhooks de direcciones y pagos: avíseme cuando lleguen fondos a estas direcciones. Es lo que necesitan los flujos de pago.
• Webhooks de eventos de contrato: avíseme cuando un contrato inteligente dado emita un evento dado. Es lo que necesitan los backends de dApps y la analítica.
• Webhooks a nivel de protocolo: notificaciones de un producto de Polygon sobre sus propias operaciones. Esas pertenecen a la documentación de ese producto, no a un escucha de cadena general.

Este artículo trata sobre el primer tipo, con notas sobre el segundo.

Por qué los webhooks superan al polling en Polygon

Polygon produce un bloque aproximadamente cada dos segundos, según esta referencia de tiempo de confirmación. Si consulta un endpoint RPC para nuevos bloques y filtra los logs usted mismo, se enfrenta a una disyuntiva sin una buena respuesta:

• Consulte cada pocos segundos y agotará los límites de tasa y pagará por respuestas mayormente vacías.
• Consulte cada minuto y su cliente mirará un indicador de carga durante un minuto después de pagar.
• Omita un rango tras un reinicio y tendrá un hueco silencioso en su contabilidad.

Los webhooks invierten esto. El proveedor se encarga de la vigilancia, los reintentos y la contabilidad de bloques. Su trabajo se reduce a ejecutar un endpoint que gestione los eventos correctamente. Profundizamos en las compensaciones arquitectónicas en nuestra publicación sobre webhooks vs WebSockets, incluido el patrón de ingesta, cola y distribución que recomendamos.

Confirmaciones, finalidad y reorganizaciones en Polygon PoS

Un webhook que se dispara al detectar por primera vez una transacción es rápido. No es definitivo. Antes de liberar bienes o acreditar un saldo, decida cuántos bloques va a esperar.

Polygon PoS confirma rápidamente. Un rastreador sitúa la primera confirmación típica entre 1 y 5 segundos, y señala que los exchanges suelen esperar 128 bloques, aproximadamente 4 a 5 minutos, para protegerse contra reorganizaciones. Otra fuente informa que la actualización Heimdall v2 en julio de 2025 redujo la finalidad dura a unos 5 segundos. Las prácticas difieren entre exchanges y herramientas, y las actualizaciones de red cambian las cifras, así que consulte la documentación actual de Polygon antes de fijar un umbral en producción.

Una forma práctica de elegir es vincular la política al valor en riesgo:

Esta tabla es nuestra política sugerida, no una regla de Polygon. Elija números que se ajusten a su propia tolerancia al riesgo y documéntelos.

En su modelo de datos, asigne a cada pago entrante un estado como detected, confirming y final. Muestre al cliente el primer estado inmediatamente y mueva los fondos solo en el último. Si su proveedor envía eventos separados a medida que se acumulan confirmaciones, úselos. Si no, almacene el número de bloque del primer evento y compárelo con la cabeza de la cadena en un temporizador.

Qué aspecto tiene un gestor de webhooks de Polygon seguro

La documentación para desarrolladores de Polygon incluye una guía sobre recepción de webhooks para uno de sus propios productos, y los principios que enseña se aplican a toda integración de webhooks: verifique la entrega y aplíquela sin doble procesamiento ni aplicación de estado obsoleto. Aquí tiene la misma disciplina para eventos de cadena.

1. Verifique la firma antes que nada

Cualquiera que encuentre su URL puede hacer POST en ella. Sin verificación, un atacante puede enviar un falso “250 USDC recibidos” y llevarse su producto. Rechace las solicitudes sin firmar o mal firmadas con un 401 y no analice el cuerpo más allá.

Chaingateway firma las solicitudes con HMAC. Usted calcula la firma sobre el cuerpo de la solicitud sin procesar con su secreto compartido y la compara usando una comparación de tiempo constante. Use los bytes sin procesar, no un objeto JSON re-serializado, porque la re-serialización cambia los espacios en blanco y el orden de las claves y rompe la coincidencia. Nuestra publicación sobre una nueva función para mejorar la seguridad de los webhooks explica las opciones de verificación en detalle.

Para una visión más amplia de la protección de claves, endpoints y procesos operativos en torno a los activos digitales, esta visión general de la seguridad y gestión de riesgos de activos digitales es una lectura útil para el lado no técnico del problema.

2. Haga que el procesamiento sea idempotente

Asuma una entrega de al menos una vez. Un tiempo de espera en su lado hace que el remitente reintente, y un reintento puede llegar después de que usted ya procesó la primera copia. Almacene una clave única por evento, idealmente el hash de la transacción más el índice del log, o el ID del evento que proporciona el proveedor. Ponga una restricción única en su base de datos:

INSERT INTO processed_events (event_key, received_at)
VALUES ($1, now())
ON CONFLICT (event_key) DO NOTHING;

Si la inserción afecta a cero filas, ya ha visto este evento. Devuelva 200 y deténgase. Haga la inserción y la actualización del saldo en la misma transacción de base de datos para que un fallo no pueda dejar una sin la otra.

3. Acuse recibo rápido, trabaje después

Devuelva un 2xx tan pronto como el evento se verifique y almacene de forma segura. Haga el trabajo lento, como enviar correos electrónicos al cliente, actualizar libros mayores y llamar a otros servicios, desde una cola. Si su manejador tarda treinta segundos, el remitente agotará el tiempo de espera y reintentará, y usted estará depurando duplicados.

4. No confíe en el orden

Dos eventos sobre el mismo pago pueden llegar en cualquier orden, por ejemplo, una actualización de confirmación antes de la detección original. Compare números de bloque o campos de secuencia e ignore cualquier cosa más antigua que el estado que ya posee. Nunca permita que un evento “detectado” tardío sobrescriba un registro “final”.

5. Valide lo que afirma la carga útil

Compruebe que el destinatario es una dirección que usted emitió, que el contrato del token es uno que usted acepta y que el importe coincide con la factura. Esto importa en Polygon más de lo que la gente espera, porque cualquiera puede desplegar un token llamado “USDC” y enviarlo a su dirección. Compare direcciones de contrato, nunca símbolos.

6. Planifique para el fallo

Su servidor se caerá en algún momento. Decida de antemano cómo se recupera:

• Use un proveedor que reintente las entregas fallidas.
• Ejecute un trabajo de conciliación, por ejemplo, cada pocos minutos, que verifique saldos o transferencias recientes para sus direcciones y marque cualquier cosa que su registro de webhooks nunca vio.
• Alerte cuando no lleguen eventos durante un tiempo inusualmente largo. En un sistema ocupado, el silencio es una señal.

Los webhooks son su vía rápida. La conciliación es su red de seguridad. Ejecute ambos.

Tokens y casos límite en Polygon

USDC y USDT. Los pagos con stablecoins son la principal razón por la que los desarrolladores configuran webhooks de Polygon, porque las comisiones son bajas y la liquidación es rápida. Asegúrese de saber qué contrato usa cada stablecoin en Polygon y ponga en lista blanca esas direcciones, como se describe arriba.

POL nativo. Las transferencias nativas no emiten logs de token, por lo que un oyente construido solo en eventos Transfer se los perderá. Confirme que su proveedor informa también de los movimientos de la moneda nativa si planea aceptar POL.

Pagos de contrato a dirección. Un pago puede provenir de una cartera de contrato inteligente o una multisig, no de una cuenta simple. No asuma que el remitente es el cliente. Vincule los pagos a los clientes mediante la dirección de recepción que generó para ellos, no por el remitente.

Transacciones fallidas y revertidas. Una transacción revertida consume gas pero no mueve nada. Actúe solo sobre eventos que representen transferencias exitosas.

Dust y tokens spam. Los tokens no solicitados aparecen regularmente en las direcciones. Ignore los contratos que no haya incluido en su lista blanca.

Constrúyalo usted mismo o use una API unificada

Hay tres rutas realistas para las notificaciones de eventos en Polygon:

1. Ejecute su propio nodo y listener. Máximo control, pero usted se encarga de las actualizaciones del nodo, el crecimiento del almacenamiento, la decodificación de logs, el manejo de reorganizaciones y la disponibilidad. Tiene sentido cuando la infraestructura de cadena es su producto.
2. Use un proveedor de nodos o datos de propósito general y escriba el filtrado usted mismo. Menor carga operativa, pero sigue construyendo suscripciones, reintentos, decodificación y la capa de firmas.
3. Use una API enfocada en pagos que entregue eventos decodificados y firmados. Usted escribe el endpoint y la lógica de negocio, nada más.

Para un equipo que quiere aceptar o enviar cripto en su producto, la tercera ruta suele llegar a producción más rápido. Comparamos las opciones con más profundidad en APIs de blockchain comparadas: 6 tipos y cuándo usar cada una.

Nuestra perspectiva: los webhooks son un problema de contabilidad, no de notificación

La mayoría de los errores de integración que vemos no tratan sobre recibir la petición HTTP. Tratan sobre lo que ocurre después. Los equipos tratan un webhook como un disparador («llegó el pago, envíelo») cuando en realidad es una entrada más para un libro mayor que debe mantenerse correcto bajo reintentos, reorganizaciones y reinicios.

Eso define cómo construimos Chaingateway. Entregamos eventos pre-decodificados, para que su código lea un importe y un token, no temas de log codificados en hex. Firmamos cada petición con HMAC para que su endpoint pueda rechazar falsificaciones. Y cubrimos Polygon junto a Ethereum, Tron, Bitcoin, Solana, BNB Chain y Arbitrum a través de una sola API REST, para que su lógica de manejo siga siendo la misma cuando añada una segunda cadena.

Nuestro consejo: escriba primero su código de idempotencia y conciliación, antes del camino feliz. Si puede reproducir el mismo evento diez veces y mezclar tres eventos y terminar con el saldo correcto, lo demás es fácil. Nuestra guía sobre procesar depósitos automáticamente con webhooks recorre ese flujo de principio a fin.

— Bitblade

Obtener webhooks de Polygon con Chaingateway

Con los Webhooks de Chaingateway crea carteras o registra direcciones a través de la API, suscríbase a eventos de pago y reciba notificaciones firmadas en su endpoint. La página de la API de Polygon cubre el envío y la recepción de USDC y USDT en Polygon, y la API de Blockchain cubre carteras, transferencias, datos de transacciones decodificados y estimación de gas en las cadenas compatibles.

Los planes se publican en la página de precios:

El acceso de pago comienza tras una prueba gratuita, para que pueda probar el flujo completo, incluidas las comprobaciones de firma y la gestión de duplicados, antes de comprometerse.

Lista de comprobación para el lanzamiento

Antes de dirigir tráfico de producción a su endpoint, revise lo siguiente:

• Solo HTTPS, con un certificado válido.
• Firma verificada en el cuerpo sin procesar, comparación en tiempo constante.
• Restricción única en la clave del evento.
• Respuesta 2xx en un par de segundos, trabajo movido a una cola.
• Direcciones de contrato en lista blanca, importes y destinatarios validados.
• Modelo de estado con estados pendientes y finales, y un umbral de confirmación documentado.
• Trabajo de conciliación y alerta para eventos ausentes.
• Secretos almacenados fuera del repositorio y rotables sin tiempo de inactividad.
• Una prueba de reenvío: envíe el mismo evento varias veces, y fuera de orden, en staging.

Preguntas frecuentes

¿Los webhooks de Polygon se disparan para POL nativo así como para tokens?

Depende del proveedor. Las transferencias de tokens emiten registros que son fáciles de rastrear, mientras que las transferencias nativas necesitan monitorización a nivel de transacción. Compruebe que su proveedor lista eventos de moneda nativa antes de confiar en él para pagos con POL.

¿Cuántas confirmaciones debo esperar en Polygon?

No hay una única regla. Algunas configuraciones tipo exchange esperan 128 bloques, unos 4 a 5 minutos, mientras que los pagos pequeños a menudo se acreditan mucho antes como pendientes. Ajuste el umbral al importe en riesgo y vuelva a comprobarlo contra la documentación actual de Polygon.

¿Qué ocurre si mi endpoint está caído cuando se dispara un evento?

Necesita dos capas: un proveedor que reintente las entregas fallidas, y su propio trabajo de conciliación que compare sus registros con la cadena. Juntas cierran las brechas incluso tras una interrupción prolongada.

¿Puede llegar el mismo webhook dos veces?

Sí, asuma que ocurrirá. Los reintentos tras tiempos de espera son la causa habitual. Almacene una clave de evento única con una restricción de base de datos y devuelva 200 para los eventos que ya haya procesado.

Fuentes

• Referencia de tiempo de confirmación de Polygon
• Tiempo de confirmación de USDT por red
• Documentación para desarrolladores de Polygon

Recomendado

• Webhooks de Blockchain y Notificaciones de Eventos
• Webhooks vs WebSockets para Desarrolladores: Patrón Ingest, Queue, Fan Out
• El uso de Webhooks para procesar depósitos automáticamente