> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Webhook (Create/Edit Webhook)

> The full-screen new/edit Webhook form under Developers > Webhooks in the merchant dashboard — enter the endpoint URL that will receive notifications, select the events to subscribe to, then create the webhook; a signing secret for verifying signatures is shown once after creation.

## 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:**

| Field                   | Meaning (merchant view)                                                                   | Notes                                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| Signature Algorithm     | The algorithm used to sign webhook notifications, fixed as HMAC-SHA512                    | Preset, cannot be changed                                                                                  |
| Version                 | The API version used for events and payloads, fixed at V1.6.0                             | Preset, cannot be changed                                                                                  |
| Endpoint URL            | The address that will receive notifications; UQPAY pushes here when events occur          | Required, must be a valid URL starting with http\:// or https\://                                          |
| Events                  | The list of events to subscribe to, checked by business line group                        | At least one required                                                                                      |
| Subscribe to all events | One-click check of all current events                                                     | Checking this won't automatically subscribe to event types added later — you'll need to come back and edit |
| Sample Payload          | Live preview on the right of sample notification content for checked events               | For reference only, can be copied                                                                          |
| Secret Key              | Shown once after successful creation, used to verify signatures on incoming notifications | Shown only once, cannot be viewed again after closing                                                      |

**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:

| Business line (as shown) | Meaning                                                           | Event groups included (examples)                                                                                                                                 |
| ------------------------ | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PLATFORM                 | Account-level events like onboarding and additional info requests | ONBOARDING (account created/updated), RFI (additional info required)                                                                                             |
| PAYMENTS                 | Acquiring/payments-related events                                 | ACQUIRING (payment intents, payment attempts, refunds, settlement, payouts, chargeback alerts, etc.)                                                             |
| GLOBAL ACCOUNTS          | Global account and fund movement events                           | BENEFICIARY, VIRTUAL (virtual accounts), DEPOSIT, PAYOUT, CONVERSION, RFI                                                                                        |
| CARDS                    | Card and card transaction events                                  | CARD (creation/update/status/recharge/withdraw), CARDHOLDER, ISSUING (card transactions, settlement, chargebacks, reports, etc.), CARD AUTH (3DS/OTP/activation) |
| CRYPTO                   | Stablecoin account ramp events                                    | CONVERSION, DEPOSIT, TRANSFER, WITHDRAW                                                                                                                          |

> 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](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.