Webhooks - UQPAY Developer Docs

SDK 提供 constructEvent 方法，用于校验 webhook 签名并返回带类型的事件对象，确保通知体未被篡改且确实由 UQPAY 发出。

前置条件

首先配置通知URL，并了解Webhook投递与安全机制。创建 client 时传入 webhookSecret：

const client = new UQPayClient({
  clientId: 'your-client-id',
  apiKey: 'your-api-key',
  webhookSecret: 'whsec_...',
})

校验并处理事件

webhook 路由必须使用原始请求体解析器。不要用 express.json()——签名校验需要原始请求体的字符串或 Buffer。

import express from 'express'

const app = express()

app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  let event

  try {
    event = client.webhooks.constructEvent(req.body, req.headers)
  } catch (err) {
    return res.status(400).send(`Webhook error: ${err.message}`)
  }

  switch (event.event_name) {
    case 'card.create.succeeded':
      // handle the event
      break
  }

  res.json({ received: true })
})

传给 constructEvent 的 req.body 必须是原始请求体字符串或 Buffer，不能是已解析过的 JSON 对象。