Skip to main content

​
What this is

This is the Add Webhook full-screen form under Developers > Webhooks in the merchant dashboard (page title “Add Webhook”, subtitle “Enter your endpoint URL and select events to subscribe to”). It’s reached by clicking Add Webhook at the top right of the Summary tab on the Webhooks list page. Here you enter an endpoint URL that will receive UQPAY event notifications and select which events to subscribe to; once created, the system pushes those events to that URL in real time. Editing an existing webhook uses the same full-screen form (title “Edit Webhook”), reached from the list row’s ”⋯” menu → “Edit Webhook”, where you can change the endpoint URL and subscribed events. Use this page whenever you want to start receiving real-time callback notifications for payments, accounts, card issuance, and similar events.
Creating/editing a webhook requires the corresponding permission — without it, the “Add Webhook” button and the row’s edit entry won’t be visible. The “x” at the top right of the page closes it and returns to the list without saving.

​
Steps

Create a new webhook:
  1. Go to Developers > Webhooks, and on the Summary tab click Add Webhook at the top right to open the full-screen form.
  2. Confirm Signature Algorithm and Version — both are preset and cannot be changed (signature algorithm is fixed as HMAC-SHA512, version is fixed at the current version, V1.6.0).
  3. Fill in Endpoint URL with the address that will receive notifications — it must be a full, valid URL starting with http:// or https:// (e.g. https://your-domain.com/webhooks).
  4. In the Events section below, select the events to subscribe to:
    • Events expand in three levels — business line → event group → specific event; click the expand arrow (▾) on the right of a row to expand/collapse it, and use the checkbox on the left to select that business line/event group.
    • To subscribe to everything, check Subscribe to all events at the top; you can also check just one business line, one event group, or individual events (parent rows show selected/partially-selected state).
    • Once you’ve checked events, Sample Payload on the right previews a live example of the notification content for the selected events; click the copy button at the top right to copy it.
    • The number of selected events is shown at the bottom.
  5. Once everything looks right, click Create at the bottom right.
  6. After creation succeeds, the page shows a one-time signing secret panel (“Webhook Created”): click the eye icon to show/hide the full secret, and the copy button to copy it. This secret is shown only this once — copy and save it immediately, since it’s used to verify signatures on incoming webhook notifications. Once saved, click Done, I’ve saved my secret to return to the list.
Edit an existing webhook:
  1. On the Summary tab of the Webhooks list, hover the target row and click the ⋯ menu at the end → Edit Webhook.
  2. The form pre-fills the webhook’s current endpoint URL and subscribed events (Signature Algorithm and Version keep their original values and cannot be changed).
  3. Modify the endpoint URL or add/remove subscribed events as needed.
  4. Click Save Changes at the bottom right; you’ll see “Webhook updated successfully” and return to the list. Saving an edit does not regenerate the secret.

​
Fields and statuses

Form fields: Event business lines (top-level groups) — which business lines appear depends on the products enabled on your account; unopened business lines won’t show, platform-level events are always visible:
Each business line and event group is labeled with “N events” showing how many events it contains. Expanding to the deepest level shows individual events (e.g. onboarding.account.create, acquiring.refund.succeeded) that you check one by one.

​
Edge cases and troubleshooting

  • No “Add Webhook” button on the list / no “Edit Webhook” in the row menu: usually a missing webhook write permission — ask an admin to grant it.
  • Can’t create — endpoint URL rejected: the URL must start with http:// or https:// and be well-formed; a bare domain or missing protocol is rejected.
  • Prompted to select at least one event: you can’t create a webhook with no events checked — select at least one.
  • A business line you want to subscribe to isn’t in the events list: the corresponding product hasn’t been activated on your account yet — only events for activated products appear; contact your account manager to activate it if needed.
  • Checked “Subscribe to all events” but don’t receive newly launched events: subscribing to all events only covers events that existed at the time — new event types added later aren’t automatically included, so you’ll need to edit and check them.
  • Forgot to copy the signing secret after creation / closed the secret panel: the signing secret is shown only once at creation and can’t be viewed again — go to the list row’s ”⋯” menu and use “Roll secret” to generate a new one (the old secret is invalidated immediately, so update your receiving endpoint at the same time).
  • The secret didn’t change after saving an edit: editing only updates the URL and subscribed events, never the secret — use “Roll secret” from the row menu if you need a new one.
  • Create/update fails: a red banner at the top of the form shows the failure reason — adjust as indicated and retry.

​
Common questions (Q&A)

  • Q: How do I create a new webhook? A: On the Developers > Webhooks page, Summary tab, click “Add Webhook” at the top right, fill in the endpoint URL, check the events to subscribe to, and click “Create” — copy the signing secret shown right after success.
  • Q: What should I put in the endpoint URL? Any format requirements? A: The address that will receive notifications; it must start with http:// or https:// and be a valid URL, e.g. https://your-domain.com/webhooks.
  • Q: Can I change the signature algorithm and version? A: No, they’re preset — Signature Algorithm is fixed at HMAC-SHA512 and Version is fixed at V1.6.0.
  • Q: What events can I subscribe to? A: Grouped by business line — PLATFORM, PAYMENTS, GLOBAL ACCOUNTS, CARDS, CRYPTO — with what’s shown depending on the products enabled on your account. You can check individual events, whole groups, whole business lines, or “Subscribe to all events”.
  • Q: If I check “Subscribe to all events,” will newly added events be received automatically? A: No — it only covers events that existed at that time; new event types launched later need to be checked in the edit page.
  • Q: What is the “Sample Payload” on the right? A: After checking events, it live-previews sample notification content for those events, for your integration reference, and can be copied.
  • Q: What’s the secret shown after creation? Why only once? A: That’s the signing secret used to verify webhook signatures; for security, it’s shown only once at creation — copy and save it immediately since it can’t be viewed again after closing the panel.
  • Q: What if I didn’t save the secret? A: Go to the corresponding row’s ”⋯” menu on the Webhooks list and click “Roll secret” to generate a new one; the old secret is invalidated immediately, so update your receiving endpoint right away.
  • Q: How do I modify a webhook I already created? A: Click “Edit Webhook” in the row’s ”⋯” menu, change the endpoint URL or subscribed events, and click “Save Changes” — the secret doesn’t change.
  • Q: Why can’t I create one / see the Add button? A: Usually a missing webhook write permission — ask an admin to grant it.
  • Q: Why don’t I see events for a certain business line? A: Only business lines for products already activated on your account appear; unopened ones don’t show — contact your account manager to activate them if needed.