Webhook Delivery Troubleshooting Guide

​

Overview

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

​

Quick Reference Flowchart

​

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

​

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

​

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