> ## 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.

# Webhooks

> The merchant dashboard Developers > Webhooks page — add/edit/delete webhook endpoints, subscribe to event types, view event delivery records, send test events, roll signing secrets, and re-trigger failed events.

## What this is

This is the **Webhooks** page under the **Developers** module in the merchant dashboard (left nav **Developers** → **Webhooks**; page subtitle "Receive real-time notifications when events happen on UQPAY"). Webhooks let the platform push a real-time notification to your configured endpoint whenever an event occurs (such as a successful payment, a completed payout, or a card being created). Here you can add/edit/delete webhook endpoints, choose which events to subscribe to, view the delivery record and result of each notification, and send test events, roll signing secrets, or re-trigger failed events. Next to the subtitle is a **Documents** link to the developer docs, and the top right has an **Add Webhook** button. Use this page to set up callback notifications, troubleshoot "not receiving notifications," or check whether a given event was delivered successfully.

The page has two tabs: **Summary** shows the list of configured webhook endpoints, and **Events** shows the delivery record for all events.

## Steps

Open the page:

1. In the left nav, click **Developers** → **Webhooks**.
2. It opens on the **Summary** tab by default, showing configured webhook endpoints; switch to the **Events** tab to see event delivery records.

Add a webhook: click **Add Webhook** at the top right to open the setup page, enter the endpoint URL and select events to subscribe to. Full steps are in the **create webhook** page.

Manage a webhook (on the **Summary** tab, hover a row and click the **⋯** menu at the end):

1. **Edit Webhook** — change that endpoint's URL or subscribed events (see below).
2. **Send test event** — sends a test notification to that endpoint; the delivery result appears on the **Events** tab.
3. **Roll secret** — regenerates the signing secret (see below).
4. **Delete Webhook** — deletes the endpoint, with a confirmation dialog; deletion cannot be undone.

Edit a webhook: click "Edit Webhook" to open the full-screen edit page. You can change the **Endpoint URL** and subscribed events; **Signature Algorithm** (HMAC-SHA512) and **Version** are fixed and cannot be changed. Click **Save Changes** when done.

Roll the signing secret (the signing secret verifies that a received notification really came from UQPAY):

1. On the **Summary** tab, click **Roll secret** in that webhook's **⋯** menu.
2. The dialog warns "A new signing secret will be generated and the current one stops working immediately" — confirm by clicking **Roll secret**.
3. The new secret is shown **once**, in a dialog (click the eye icon to reveal the plaintext, and the copy button to copy it). **This secret is shown only this once — it cannot be viewed again after closing the dialog**, so copy it immediately and update your receiving endpoint.
4. Once saved, click **Done, I've saved my secret** to close.

> After rolling, the old secret is invalidated immediately — be sure to update your endpoint's signature-verification logic with the new secret first, or subsequent notifications will fail verification.

View delivery records on the **Events** tab:

1. The list shows delivery records for all webhooks.
2. Use the toolbar to filter: **Filter by status** (All Status/Success/Failed/Pending), and search by **Event name**, **Event type**, **Source ID**, or **Event ID**, or use the date range picker to filter by date (up to the last 90 days).
3. Applied filters appear as tags below; click the "x" on a tag to remove it, or **Clear all** to reset.

View a single event's details and retry it:

1. Click the **⋯** menu at the end of a row → **View Details** to open the **Event Details** panel on the right.
2. The panel shows event status, HTTP status, attempt count, event name/type/ID, webhook URL, the HTTP error (if it failed), and the full request payload (copyable).
3. Click **Re-Trigger** at the top right of the details panel to resend the event; this is typically used for events that failed delivery.

## Fields and statuses

**Summary tab list columns:**

| Column           | Meaning (merchant view)                                                |
| ---------------- | ---------------------------------------------------------------------- |
| Notification URL | The endpoint address receiving notifications                           |
| Version          | This webhook's event version (e.g. V1.6.0), fixed after creation       |
| Subscribed       | The number of events this endpoint subscribes to (shown as "N events") |

**Events tab list columns:**

| Column     | Meaning (merchant view)                                                       |
| ---------- | ----------------------------------------------------------------------------- |
| Time       | When the event occurred                                                       |
| Event name | The business category name the event belongs to                               |
| Event type | The specific event type identifier (e.g. acquiring.payment\_intent.succeeded) |
| Attempts   | The number of delivery attempts made for this event                           |
| Source ID  | The ID of the business object that triggered the event (click inline to copy) |
| Event ID   | The unique ID of this event (click inline to copy)                            |
| Status     | The notification's delivery status, see below                                 |
| Updated    | When this event was last updated                                              |

**Event delivery status:**

| Status  | Meaning                                                                 |
| ------- | ----------------------------------------------------------------------- |
| Success | The notification was delivered to your endpoint successfully            |
| Failed  | Delivery failed (hover over the status badge to see HTTP error details) |
| Pending | The notification delivery is in progress                                |

**Event details panel fields:** Status, HTTP Status, Attempts, Time, Event name, Event type, Event ID, Webhook URL, HTTP Error (shown only when failed), Request Payload (full JSON, copyable).

**Subscribed event categories:** when adding/editing a webhook, events are grouped by business line and can be checked individually, by group, by whole business line, or all at once via "Subscribe to all events." Five categories exist (which business lines appear depends on the products enabled on your account; unopened ones won't show):

| Category        | Events covered (examples)                                                                    |
| --------------- | -------------------------------------------------------------------------------------------- |
| PLATFORM        | Account onboarding, RFI additional-info requests, etc.                                       |
| PAYMENTS        | Acquiring payment intents, payment attempts, refunds, settlement, chargeback alerts, etc.    |
| GLOBAL ACCOUNTS | Beneficiaries, virtual accounts, deposits, payouts, currency conversion, etc.                |
| CARDS           | Cards, cardholders, card issuance, card authorization, card account deposits/transfers, etc. |
| CRYPTO          | Stablecoin account conversion, deposits, transfers, withdrawals, etc.                        |

> Checking **Subscribe to all events** only subscribes to the event types that currently exist; event types added in the future are not automatically monitored — come back and edit your selection when needed.

**Fixed fields on the edit page:**

| Field               | Meaning                                                                                      |
| ------------------- | -------------------------------------------------------------------------------------------- |
| Signature Algorithm | The algorithm used to sign notifications (HMAC-SHA512), fixed and cannot be changed          |
| Version             | This webhook's event version, fixed after creation                                           |
| Endpoint URL        | The address receiving notifications; must be a valid URL starting with http\:// or https\:// |

## Edge cases and troubleshooting

* **Summary shows "No webhooks yet"**: no endpoint has been configured yet; the hint reads "Add a webhook to receive real-time notifications." — click **Add Webhook** to create one.
* **Events shows "No events yet"**: there's no delivery record yet; the hint reads "Webhook events will appear here once triggered." — try **Send test event** first to verify.
* **Not receiving notifications / want to confirm whether one was actually sent**: switch to the **Events** tab, filter by Event ID / Source ID or status to locate the event, and click **View Details** to check delivery status, HTTP status, and any HTTP error; failed ones can be resent via **Re-Trigger**.
* **A particular event failed delivery**: the details panel shows the HTTP status and HTTP error — use it to diagnose your endpoint's availability, then **Re-Trigger** once fixed.
* **Want to verify an endpoint is configured correctly**: click **Send test event** in that row's "⋯" menu on the **Summary** tab, then check the delivery result of that test notification on the **Events** tab.
* **After changing the URL, are the originally subscribed events still there?**: yes — editing only changes the URL and leaves the event selection untouched; the change takes effect immediately on save.
* **Can't find older events**: the event time filter only covers the last 90 days.
* **No "Add Webhook" / row "⋯" menu / "Re-Trigger" button visible**: these are management actions requiring webhook write permission — without it you can only view, not add/edit/delete or retry; ask an admin to grant permission.

## Common questions (Q\&A)

* **Q: Where do I configure webhooks? / How do I add a callback address?** A: Left nav **Developers** → **Webhooks** → **Summary** tab → **Add Webhook** at the top right, then enter the endpoint URL and check events — see the create webhook page for details.
* **Q: How do I change a webhook's address or subscribed events?** A: On the **Summary** tab, open that row's "⋯" menu → **Edit Webhook**, change the endpoint URL or checked events, then click **Save Changes**.
* **Q: My webhook isn't receiving notifications — how do I troubleshoot?** A: Switch to the **Events** tab, filter by status/Event ID/Source ID to locate the event, and click **View Details** to see the delivery status and HTTP error; failed ones can be resent via **Re-Trigger**.
* **Q: How do I test whether a webhook works?** A: In that row's "⋯" menu on the **Summary** tab, click **Send test event**, then check the delivery result on the **Events** tab.
* **Q: Can a failed event delivery be retried?** A: Yes. On the **Events** tab, click **View Details** for that row, then click **Re-Trigger** in the details panel.
* **Q: What event statuses are there?** A: Success, Failed, and Pending; hover over the status badge on a failed event to see the HTTP error details.
* **Q: What does "Attempts" mean?** A: The number of times delivery to your endpoint has been attempted for that event.
* **Q: What events can I subscribe to?** A: Five categories by business line — PLATFORM, PAYMENTS, GLOBAL ACCOUNTS, CARDS, CRYPTO — each with several specific event types; you can select individually, by group, or select all. Which categories appear depends on the products enabled on your account.
* **Q: Does "Subscribe to all events" automatically include events added later?** A: No — it only subscribes to event types that exist at the time; new types added later need you to come back and edit your selection.
* **Q: What if I forgot / leaked the signing secret?** A: In that row's "⋯" menu on the **Summary** tab, click **Roll secret** to generate a new one — copy it immediately and update your receiving endpoint, since the old secret is invalidated right away.
* **Q: Can I view the signing secret again?** A: No. It's shown only once at generation and can't be viewed again after the dialog is closed — roll a new one if you need it.
* **Q: What signature algorithm does the webhook use?** A: HMAC-SHA512, visible on the edit page and fixed — it cannot be changed.
* **Q: Can I change the webhook's version?** A: No. The version is fixed at creation and shown as unchangeable on the edit page.
* **Q: How far back can I query events?** A: The event time filter supports up to the last 90 days.
* **Q: Why don't I see the add/edit/delete buttons?** A: These management actions require webhook write permission — without it you can only view; ask an admin to grant permission.
* **Q: Can a deleted webhook be recovered?** A: No, deletion cannot be undone and requires a confirmation dialog.