API Webhook Delivery Status and Troubleshooting
How to read the webhook rows in account settings, what last error means, how retry timing works from a user standpoint, and how to troubleshoot PAT and webhook setup problems.
API Webhook Delivery Status and Troubleshooting
Where you see this in the app
This page explains the Personal Access Tokens and Webhooks area in /settings/api.
The current settings page is lightweight. It focuses on creating tokens, adding webhook endpoints, deleting old entries, and showing the latest webhook error context when something fails.
Personal access tokens vs webhooks
These two tools solve different problems:
| Tool | Use it when you want to |
|---|---|
| Personal access token | Call GetPaidX APIs from your own script, app, workspace, or automation client |
| Webhook | Let GetPaidX call your endpoint when subscribed events happen |
A PAT is for outbound calls from your side into GetPaidX. A webhook is for outbound calls from GetPaidX into your side.
Webhook rows and last error
Each webhook row on the current settings page shows:
| Field | What it means |
|---|---|
| URL | The destination GetPaidX will try to call |
| Events | The event types subscribed for that destination |
| Last error | The latest failure message stored for that webhook, if any |
Some retry details are not shown as a full deliveries table in the current page yet. So if you only see last error, that is expected for the present UI.
| Failure pattern | What to check |
|---|---|
| Wrong or outdated URL | Confirm the endpoint path still exists and is publicly reachable |
| Signature validation failure | Confirm your endpoint expects the right signing secret and header format |
| 4xx response | Your endpoint rejected the payload or auth assumptions |
| 5xx response | Your server had an internal failure and GetPaidX could not complete delivery |
| Timeout or unreachable host | Your endpoint could not be reached in time |
Delivery retry behavior and failures
Webhook delivery is retried automatically for failures up to a limit. From an end-user perspective, this means a temporary outage does not always require recreating the webhook immediately.
| Situation | What to do |
|---|---|
| One recent failure after a deployment | Fix the receiver first and let retries catch up |
Repeated failure with the same last error | Verify URL, secret, and response status handling |
| Old webhook no longer needed | Delete it instead of leaving a broken endpoint subscribed |
If your webhook receiver rotates secrets, GetPaidX must also be updated to use the new secret. Otherwise every delivery will fail signature validation.
What to check before recreating
Before deleting and recreating a PAT or webhook, check:
- whether the destination URL is still valid,
- whether your receiver expects the same secret and event list,
- whether the failing workflow should use a PAT instead of a webhook,
- whether your server is returning success fast enough.
For PAT troubleshooting, the usual user-facing checks are:
| Symptom | What to check |
|---|---|
| Request is rejected immediately | Confirm the token still exists and has the required scopes |
| Some APIs work but billing actions fail | Some billing and Stripe actions are intentionally session-only, not PAT-enabled |
| Workspace/API call works locally but not elsewhere | Check whether the token value, environment, or IP restrictions changed |
Related docs
Related docs
See it in action