La firma no coincide
La causa más común es firmar el JSON analizado en lugar del cuerpo sin formato exacto, o usar una marca de tiempo diferente a la del encabezado de la solicitud.
Probador de Webhooks
Prueba tus WebhooksVerifica la firma
Edita un cuerpo de ejemplo y genera una firma HMAC-SHA256 y una solicitud cURL para tu entorno de prueba.
01
Configura la prueba
Introduce la URL, la clave de prueba y la marca de tiempo.
La firma se calcula en el navegador. Usa una clave de prueba.
Marca de tiempo Unix en milisegundos, como en los encabezados de BoltUtil.
02
Edita el cuerpo y genera la firma
La firma y cURL se actualizan al editar el JSON.
Firma
HMAC-SHA256Introduce una clave, una marca de tiempo y un JSON válidos.
Calculada con la marca de tiempo, el cuerpo original y la clave de prueba.
JSON válido
cURL / POSTSolicitud de prueba
Introduce una URL, una clave, una marca de tiempo y un JSON válidos.Ejemplo de callback de una orden USDC, adaptable a USDT. La orden, las direcciones y el hash son ficticios y no acreditan un pago.
La herramienta no envía solicitudes. Ejecuta cURL manualmente en tu entorno de prueba.
Verificación
Verifica antes de continuar
Verifica con la misma regla, guarda el evento y actualiza la orden.
Ver guía de verificaciónHMAC_SHA256(timestamp + "." + rawBody, secret)- 01
Verificar el cuerpo crudo
Utilice la marca de tiempo de milisegundos del encabezado y el cuerpo sin formato exacto para calcular HMAC antes de analizar JSON. Los espacios en blanco, los saltos de línea y el orden de los campos afectan la firma.
- 02
Utilice una comparación segura en el tiempo
Compare la firma recibida con un asistente de tiempo constante proporcionado por el tiempo de ejecución de su idioma.
- 03
Graba de forma segura y luego regresa 2xx
Solo se obtiene el éxito después de registrar el evento o colocarlo en una cola interna duradera.
Diagnóstico de Webhooks
Por qué puede fallar un Webhook de pago
La mayoría de problemas vienen de verificación de firma, parseo del body, gestión de reintentos o devolver éxito antes de registrar el evento de pago.
secreto equivocado
Utilice el secreto del webhook configurado para el punto final del comerciante. Las claves de API y los secretos de webhook deben tratarse como credenciales diferentes.
El analizador corporal cambió la carga útil
El middleware JSON puede reordenar o reformatear cargas útiles. Capture el cuerpo sin formato antes de analizarlo al verificar las firmas HMAC.
El punto final devuelve no-2xx
Un estado distinto de 2xx indica fallo. Los reintentos dependen del tipo de callback, del estado HTTP y de la política de reintentos.
El procesamiento no es idempotente.
Deduplica por identificador de orden y estado, o por un ID de evento único. Un hash puede incluir varias transferencias.
Éxito antes que durabilidad
Devuelva HTTP 2xx solo después de escribir el evento en su base de datos o cola. De lo contrario, una falla puede hacer perder una notificación de pago completada.
Preguntas frecuentes
Preguntas de depuración Webhook
Usa estas comprobaciones cuando el pago está completado pero tu aplicación no se actualiza.
¿Por qué falla la verificación de la firma de mi webhook?
Verifique el cuerpo exacto de la solicitud sin procesar, el encabezado de la marca de tiempo y el secreto del webhook configurado. La firma de JSON analizado o un cuerpo reformateado generalmente produce un HMAC diferente.
¿El punto final de mi webhook debería devolver ÉXITO en el cuerpo de la respuesta?
No. BoltUtil usa el estado HTTP: 2xx indica recepción correcta. Verifica y guarda el evento antes de responder.
¿Cómo debo manejar las entregas de webhooks duplicados?
Usa una restricción única o una operación atómica por orden y estado, o ID de evento. No uses solo el hash de la transacción.
¿Cuándo debería devolver mi terminal HTTP 2xx?
Devuelve 2xx tras verificar y guardar el evento. Si falla, devuelve un error adecuado; los reintentos dependen del tipo de callback y la política.