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

# Webhook Delivery Troubleshooting Guide

> Diagnose and resolve issues when expected webhook events are not being received by your endpoint.

## Overview

This guide helps troubleshoot cases where customers report not receiving expected webhooks.

## Quick Reference Flowchart

```mermaid theme={null}
flowchart TD
    A[Customer reports missing webhook] --> B{Check webhook subscription}
    B -->|Not subscribed| C[Webhook not subscribed<br/>UQPAY will not send webhook]
    B -->|Subscribed| D[Check Webhook Logs in Dashboard]
    D --> E{Webhook record found?}
    
    E -->|Yes| F[Webhook was sent]
    E -->|No| G[Webhook was not sent]
    
    F --> H{Response status code?}
    H -->|200 OK| I[Webhook received and processed successfully]
    H -->|Non-200| J[Client-side issue]
    
    J --> K[Check IP whitelist]
    J --> L[Check endpoint availability]
    J --> M[Check SSL certificate changes]
    J --> N[Check webhook endpoint logic]
    J --> O[Re-trigger webhook if needed]
    
    G --> P[Contact UQPAY Support]
    P --> Q[Provide required information]
    
    I --> R[Webhook was processed correctly<br/>Check client-side application logs]
    
    C --> S[Subscribe to webhook event type]
    
    style I fill:#90EE90
    style J fill:#FFB6C1
    style G fill:#FFD700
    style P fill:#FFD700
    style C fill:#FFA500
    style S fill:#87CEEB
```

## Step-by-Step Troubleshooting Process

### Step 1: Verify Webhook Subscription

**This is the first and most critical step.**

Before investigating any further, verify that you have subscribed to the specific webhook event type that you expect to receive. If the webhook event type is not subscribed, UQPAY will not send the webhook notification.

**How to check webhook subscription:**

1. Log in to your UQPAY dashboard
2. Navigate to **Settings** → **Developer** → **Webhooks** → **Summary**
3. Verify that the expected webhook event type is subscribed
4. Check the webhook Notification URL is correctly configured

For detailed instructions, refer to [Webhook Settings Documentation](/account-center/v1.6/guide/webhooks-setting).

**If not subscribed:**

* Subscribe to the required webhook event type in the dashboard
* Configure the webhook endpoint URL
* **Important:** After successfully subscribing to a webhook event type, UQPAY will only send webhooks for events that occur after the subscription is activated. Webhooks for events that occurred before the subscription cannot be retroactively delivered.

**If subscribed:** Proceed to Step 2.

### Step 2: Check Webhook Logs in Dashboard

Navigate to the **Webhook Logs** page in your dashboard to check if there are any records for the expected webhook.

**How to access Webhook Logs:**

1. Log in to your UQPAY dashboard
2. Navigate to **Settings** → **Developer** → **Webhooks** → **Events**
3. Filter by:
   * Event type
   * Time range
   * Status
   * Reference ID

### Step 3: Analyze the Results

#### Scenario A: Webhook Record Found

If the webhook record exists in the logs, this indicates that UQPAY successfully sent the webhook to your endpoint.

**Check the response status code:**

| Status Code | Meaning                                                                                                                                                                                  | Action Required                                                                                                           |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| **200 OK**  | A 200 HTTP status code response indicates that your endpoint successfully received and processed the webhook. UQPAY considers the webhook delivery complete and will not retry.          | The webhook was delivered correctly. Check your application logs to verify if the webhook data was processed as expected. |
| **Non-200** | A non-200 response indicates that your endpoint did not properly handle the webhook. UQPAY will trigger a retry mechanism and resend the webhook according to a specific retry schedule. | Proceed to **Client-Side Troubleshooting** below.                                                                         |

#### Scenario B: No Webhook Record Found

If no webhook record exists in the logs, this indicates that UQPAY did not send the webhook.

**Action Required:** Contact UQPAY technical support with the information specified in the **Information Collection** section below.

## Client-Side Troubleshooting

If the webhook was sent but returned a non-200 status code, follow these steps:

### 1. Check IP Whitelist

Ensure that [UQPAY's webhook server IP addresses](/account-center/v1.6/guide/webhooks-overview) are whitelisted in your firewall or security group.

### 2. Verify Webhook Endpoint Availability

* **Endpoint accessibility:** Ensure your webhook endpoint is publicly accessible
* **Recent SSL certificate changes:** Check if you recently renewed or replaced your server certificate
* **Network connectivity:** Check if there are any network issues preventing UQPAY from reaching your endpoint

### 3. Review Webhook Endpoint Logic

Check your webhook handler implementation:

* **Request parsing:** Verify that request body parsing is correct
* **Error handling:** Check if exceptions are being caught and handled properly
* **Response format:** Ensure your endpoint returns HTTP 200 with a valid response body

### 4. Re-trigger Webhook

You can re-trigger a webhook from the dashboard to resend it. This can help test whether your endpoint fixes are working correctly.

**How to re-trigger a webhook:**

1. Navigate to **Settings** → **Developer** → **Webhooks** → **Events**
2. Find the failed webhook record
3. Click **Re-trigger** to resend the webhook

For detailed instructions, refer to [Webhook Settings Documentation](/account-center/v1.6/guide/webhooks-setting).

## Information Collection for UQPAY Support

If no webhook record is found in the dashboard, this indicates that UQPAY did not send the webhook. To help our technical team investigate the issue, please provide the following essential information:

### Required Information

| Field                  | Description                                                                                                                                                                                            | Example                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| **Webhook Event Type** | The specific webhook event type that was not received                                                                                                                                                  | `beneficiary.successful`, `card.create.succeeded`, `acquiring.payment_intent.created`, etc. |
| **Resource ID**        | The ID of the resource that should have triggered the webhook. Use the appropriate resource ID based on the webhook type (e.g., Payment Intent ID for payment webhooks, Payout ID for payout webhooks) | PaymentIntent ID, Card ID, Payout ID, etc.                                                  |