Integración de webhook
Un webhook informa un evento de cuenta al receptor URL. Es una notificación; verifique el estado de la transacción autorizada a través de transacción GET.
Configurar el receptor
En la configuración del webhook de Heth, configure un URL que usted controle, configure el secreto de integración y habilite la entrega. Cambiar el URL cambia quién recibe los eventos de la cuenta. Proteja ese punto final y evite redirecciones a destinatarios que no sean de confianza. La configuración requiere la sesión de la cuenta del usuario; una clave API utilizada para transacciones no es automáticamente suficiente.
Procesar notificaciones de forma segura
- Valide la firma del webhook de la cuenta y vuelva a realizar las comprobaciones que se describen a continuación.
- Registre el identificador de evento/transacción con los campos confidenciales redactados.
- Hacer que el manejo sea idempotente: la entrega duplicada o retrasada no debe generar otro pago.
- Recupera la transacción con tu propia credencial y concilia su estado.
- Devuelve la respuesta del receptor requerida por el contrato de entrega configurado.
No trate una notificación push del navegador como un webhook o una garantía de entrega. Esta descripción general no promete pedidos, intervalos de reintento o un formato de autenticación común para cada integración configurada. Obtenga el contrato de entrega real antes de habilitar la automatización de la producción.
Formato de entrega del webhook de la cuenta
Este formato se aplica a los webhooks de cuentas configurados en la configuración de Heth. Otras integraciones de devolución de llamada pueden utilizar un contrato diferente.
Cuando se configura un secreto de webhook de cuenta que no está vacío, la solicitud incluye x-webhook-signature (hexadecimal HMAC-SHA256), x-webhook-timestamp (segundos de Unix) y x-webhook-event-id. Verifique el HMAC con la marca de tiempo + "." + los bytes exactos del cuerpo HTTP sin procesar utilizando el secreto configurado; no analice ni vuelva a serializar JSON antes de la verificación. Verifique que la marca de tiempo del cuerpo firmado coincida con el encabezado de la marca de tiempo, rechace una diferencia de reloj superior a los minutos 5, compare firmas en tiempo constante y realice la deduplicación mediante event_id. Un reintento conserva event_id pero recibe una marca de tiempo/firma nueva. Sin un secreto configurado, los encabezados de firma pueden faltar; configure un secreto antes de confiar en la entrega automatizada.
hex(HMAC-SHA256(secret, timestamp + "." + raw_body))
El sobre tiene event_id, marca de tiempo, tipo y datos. Para eventos de transacciones de cuenta, los datos incluyen tx_id, txid, tipo, estado, monto, moneda y tipo de evento. La cantidad puede ser un número entero JSON: utilice un analizador sin pérdidas. Una donación puede agregar un objeto de donación. Reconocer un evento verificado con HTTP 2xx después de grabarlo; Los valores repetidos de event_id verificados no deben desencadenar la acción comercial dos veces. Confirme la transacción a través de GET incluso después de una notificación válida.