Skip to main content

​
Webhooks

Requires Growth tier or above
Webhooks send HTTP POST requests to your server when events happen in uPayments.

​
Two Types of Events

​
Payment Page & Invoice Events (Real-time)

Fired instantly when customers interact:
  • payment_page.payment — Payment received
  • payment_page.form_start — Customer started filling form
  • invoice.sent — Invoice emailed to customer
  • invoice.paid — Invoice paid
  • invoice.overdue — Invoice past due date

​
Synced Data Events (Batched)

Fired after each NMI sync cycle:
  • transaction.approved — New approved transaction synced
  • transaction.declined — New declined transaction synced
  • transaction.settled — Transaction settled
  • transaction.refunded — Refund synced
  • subscription.created — New subscription detected
  • subscription.cancelled — Subscription expired/cancelled
  • customer.created — New customer extracted
Synced data events fire after each sync cycle (every 15 minutes). They may include transactions that your NMI gateway already processed — these webhooks notify your system that the data is now available in uPayments.

​
Security

All webhooks are signed with HMAC-SHA256. The signature is sent in the X-Webhook-Signature header. Verify by computing HMAC-SHA256(webhook_secret, request_body) and comparing to the header value.

​
Retry Policy

  • Failed deliveries are retried up to 5 times
  • Exponential backoff: 30s, 2m, 10m, 1h, 6h
  • After 5 failures, the webhook is paused

​
Creating a Webhook

  1. Go to Settings → Webhooks
  2. Click Add Webhook
  3. Enter the endpoint URL
  4. Select events to subscribe to
  5. Optionally set a signing secret (recommended)

​
Payload Format

{
  "event": "payment_page.payment",
  "timestamp": "2026-03-23T14:30:00Z",
  "data": {
    "transaction_id": "txn_abc123",
    "amount": 49.99,
    "currency": "USD",
    "customer": {
      "email": "customer@example.com",
      "name": "John Doe"
    },
    "page": {
      "id": "page_xyz",
      "title": "Premium Plan"
    }
  }
}