Webhooks - UQPAY Developer Docs

The SDK provides a constructEvent method that verifies the webhook signature and returns a typed event object. This ensures the payload has not been tampered with and was sent by UQPAY.

Prerequisites

First, configure a notification URL and review the webhook delivery and security model. Set the webhookSecret when you create the client:

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

Verify and handle events

Use a raw body parser for your webhook route. Do not use express.json() — the signature verification requires the original request body as a string or 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 })
})

The req.body passed to constructEvent must be the original request body string or Buffer, not a parsed JSON object.