Webhook Verificación de firma e idempotencia
Verifique los cuerpos Webhook sin procesar, reconozca el uso de códigos de estado HTTP y maneje los reintentos y duplicados de manera confiable.
Esta página sigue Agent Java SDK WEBHOOKS.md en el compromiso fa6c7b6. Esta es una actualización de documentación únicamente; no se lanzó ningún nuevo artefacto SDK que contenga métodos auxiliares de advertencia.
Los cuatro tipos de eventos utilizan una devolución de llamada del comerciante URL y son enviados por el cuerpo event. Ver Webhook Eventos y advertencias de liquidación para campos de eventos y ejemplos de carga útil.
Webhook encabezados
Idempotencia del evento
Persista la deduplicación dentro del comerciante y environment alcance, atómicamente con el procesamiento comercial. Diferentes valores notificationId identifican notificaciones FIRST / UPGRADE / REMINDER independientes; no descartes las notificaciones agrupándolas por usuario, episodio o eventType. No se puede utilizar una clave de idempotencia vacía para la deduplicación. El SDK solo devuelve una clave auxiliar; no persiste ni procesa datos comerciales. Registrar la misma identidad con un organismo diferente como conflicto; no sobrescriba el cuerpo procesado.
Verificación y recepción de firma.
Utilice el secreto comercial API para calcular la firma hexadecimal HMAC-SHA256 de timestamp + nonce + rawBody. Verifique los bytes recibidos originales; no formatee JSON, cambie el nombre de los campos ni vuelva a serializar el cuerpo primero.
Primero verifique la firma, luego verifique la ventana de tiempo (recomendado ±300 segundos), el comerciante y el entorno. A continuación, extraiga la identidad de idempotencia y maneje la notificación de manera confiable. Preservar valores de eventos desconocidos para el diagnóstico; Nunca los interpretes como éxito de los fondos. El asistente de verificación no realiza comprobaciones de ventana de tiempo, propiedad o deduplicación persistente.
Devuelve HTTP 2xx después de completar el procesamiento o confirmar un duplicado idéntico; devolver no-2xx en caso de error. El remitente de la advertencia tiene un tiempo de espera de 5 segundos HTTP y como máximo 8 intentos. Los reintentos retienen el cuerpo congelado; solo cambian la marca de tiempo de la firma y el nonce. Responder con prontitud después de una aceptación confiable; El trabajo comercial de larga duración puede utilizar las tareas persistentes del propio comerciante.
Las notificaciones de los comerciantes no dependen del estado en línea del usuario. Los envíos de los usuarios de la plataforma se realizan únicamente en línea con el mejor esfuerzo posible, sin repetición fuera de línea; La fase uno no tiene bandeja de entrada de notificaciones.
Respuestas exitosas y detención de reintentos
Las devoluciones de llamada de fondos y las advertencias de liquidación utilizan solo el código de estado HTTP para determinar el éxito de la entrega. El remitente no interpreta el cuerpo de la respuesta code, success, result o message, y no requiere una respuesta fija OK/success.
El cuerpo de la respuesta puede estar vacío, texto o JSON. Los campos de ejemplo result son informativos para el comerciante, no requisitos de protocolo. 202 Accepted también detiene los reintentos de la plataforma, así que devuélvalo solo después de guardar de manera confiable la notificación en la cola de tareas persistentes del comerciante, no simplemente iniciando una tarea asíncrona en memoria.
Ejemplos de respuestas exitosas
Una vez que se completa el procesamiento comercial o la notificación se guarda de manera confiable en la cola pendiente del comerciante:
Cuando no se necesita un cuerpo de respuesta:
Para una notificación ya procesada con un cuerpo idéntico, omita el procesamiento comercial duplicado y aún así devuelva 2xx:
Ejemplos de respuesta a fallos
Si la base de datos no está disponible temporalmente y el comerciante no completó el procesamiento ni guardó de manera confiable la notificación, devuelva non-2xx para que la plataforma pueda volver a intentarlo:
Rechazar una firma no válida sin actualizar datos comerciales o registros de deduplicación exitosos:
Estos cuerpos de respuesta no cambian las decisiones de reintento. No espere que un 401 o 409 detenga permanentemente los reintentos; investigue la firma, el contenido de la notificación o la configuración del comerciante.
Ejemplo incorrecto: la siguiente respuesta aún cuenta como entrega exitosa. La plataforma no volverá a intentarlo debido a success:false.
Si el marco o el controlador de excepciones global envuelve las fallas comerciales en HTTP 200, establezca explícitamente el estado de falla correcto en el punto final de devolución de llamada.
Acuse de recibo confiable y entrega duplicada
Orden recomendado: verificar la firma y verificar la hora/comerciante/entorno → extraer la identidad de idempotencia → procesar datos comerciales y registros de deduplicación exitosos en una transacción, o guardar de manera confiable una tarea pendiente → devolver 200/204 después de que la confirmación sea exitosa. No devuelva 2xx ni marque la notificación procesada antes de una escritura exitosa en la base de datos.
Aún puede ocurrir una entrega duplicada después de que el procesamiento del comerciante sea exitoso: la respuesta puede perderse o la plataforma puede recibir 2xx pero no persistir SUCCESS. HTTP las devoluciones de llamada no garantizan una entrega única. Mantener la deduplicación dentro del alcance del comerciante y environment. Uso de fondos orderType:orderId:targetStatus; las advertencias utilizan liquidation.warning:notificationId. Para un cuerpo idéntico ya procesado, devuelva 2xx sin acreditar fondos ni emitir un recordatorio nuevamente. Para la misma identidad con un cuerpo diferente, registre un conflicto y devuelva un valor distinto de 2xx; no sobrescriba el registro original.
El reconocimiento exitoso significa que el comerciante recibió/procesó la notificación, no que la operación de fondos se realizó correctamente. Después de registrar una notificación de fondos válida con targetStatus=FAILED, devuelva también 2xx; el fracaso del pedido no es motivo para rechazar el acuse de recibo de la notificación.
Límites de financiación y medio ambiente
El flujo de transferencia de contrato original webhook y queryOrder no se aplica automáticamente a la financiación. Confirme las operaciones de financiación utilizando queryWalletTransfer y el entorno de pedido original. Usos de la financiación status; Las respuestas originales de transferencia de contrato utilizan orderStatus. Una respuesta HTTP exitosa o code=0 no prueba por sí sola que se hayan movido fondos.
Las notificaciones explícitas de transferencia de contrato simuladas incluyen environment=SIMULATED. Primero verifique el cuerpo sin procesar, luego verifique el usuario, el monto, la identidad del pedido y el entorno con el pedido comercial local guardado.