Webhook Event Catalog

Overview

Webhooks notify your application when events occur in Wallgent. Register a webhook URL and subscribe to the events you care about.

Every webhook payload includes:

Verifying webhook signatures

Every webhook delivery includes a Wallgent-Signature header with an HMAC-SHA256 signature. Always verify this in production.

Using the SDK:

import { verifyWebhookSignature } from '@wallgent/sdk'
import express from 'express'

const app = express()

// Express example
app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['wallgent-signature'] as string
  const secret = process.env.WALLGENT_WEBHOOK_SECRET!

  const isValid = verifyWebhookSignature(req.body, signature, secret)
  if (!isValid) {
    return res.status(401).json({ error: 'Invalid signature' })
  }

  const event = JSON.parse(req.body.toString())
  // Process event...
  res.json({ received: true })
})

The req.body must be the raw request body bytes, not parsed JSON. Use express.raw() or the equivalent for your framework.

Header format: Wallgent-Signature: sha256=<hex-digest>

The SDK computes HMAC-SHA256(secret, rawBody) and compares it to the hex digest in the header using a constant-time comparison to prevent timing attacks. The function returns true if the signature is valid and false otherwise.

Getting your webhook secret: Find it in the dashboard under Settings → Webhooks, or retrieve it from the webhook object returned when you create a webhook via POST /v1/webhooks. The secret is only shown once — if you lose it, delete the webhook and create a new one.

Payment Events

payment.completed

Sent when a wallet-to-wallet payment is posted successfully.

payment.failed

Sent when a payment attempt fails.

payment.pending

Sent when a payment is created but awaiting approval.

payment.reversed

Sent when a payment is reversed.

Wallet Events

wallet.created

wallet.funded

wallet.frozen

wallet.unfrozen

wallet.closed

wallet.funds_pending

Funds deposited but held for clearing.

wallet.funds_available

Held funds released and available for use.

wallet.balance_negative

Wallet balance went negative (e.g., after a clawback).

Policy Events

policy.denied

Sent when a policy blocks a payment.

policy.created

policy.updated

Approval Events

approval.requested

Sent when a payment requires human approval.

approval.approved

approval.rejected

approval.expired

Limit Events

limit.approaching

Sent when spending approaches a policy limit (e.g., 80% of daily limit).

limit.exceeded

Deposit & Withdrawal Events

deposit.initiated

deposit.completed

deposit.failed

withdrawal.initiated

withdrawal.completed

withdrawal.failed

Card Events

card.created

card.updated

card.cancelled

card.authorization.approved

card.authorization.declined

card.authorization.captured

card.authorization.reversed

card.refund.created

Payment Link Events

payment_link.created

payment_link.claimed

payment_link.settled

payment_link.expired

payment_link.cancelled

Invoice Events

invoice.created

invoice.finalized

invoice.paid

invoice.payment_failed

invoice.voided

invoice.refunded

invoice.uncollectible

invoice.usdc_unmatched

USDC payment received that couldn't be matched to an invoice.

Customer Events

customer.created

customer.updated

customer.payment_method.saved

customer.payment_method.updated

customer.payment_method.removed

API Key Events

api_key.expiring_soon

Sent 7 days before an API key expires.

api_key.auto_revoked

Sent when an expired API key is automatically revoked.