Webhooks Overview
WebhooksAPI provide real-time notifications to your application about events occurring on Paydude platform. This ensures applications can react promptly to events as they happen.
Within a Paydude account, some actions happen directly after you ask for them. For example, if you add a new customer, you immediately get back information about that customer. Those instances don’t trigger a webhook, however, other events within an account are asynchronous, occurring at a later time and not as a direct result of your code execution.
Common asynchronous events
- Successful processing of a pending ACH debit charge
- Notifications regarding payouts
- Changes in connected account statuses, which are particularly relevant during the onboarding process
For these asynchronous events, Paydude notifies your integration about status changes, enabling your system to take appropriate follow-up actions. The specific responses of your webhook endpoint can vary based on the event type.
Examples of actions triggered by webhooks
- Updating a customer’s membership status
- Emailing a receipt to a customer
- Signaling that an order is ready for fulfillment
How Webhooks Work
Event details are sent in JSON format, with Paydude issuing a POST request to your designated notification URL. Your server should acknowledge webhook notifications by returning a 200 response as quickly as possible — any other response code is treated as a failure and will be retried according to the schedule below.
Paydude webhook endpoints are configured at the parent account level, ensuring that notifications encompass events across all connected accounts.
Retry Schedule
When a delivery attempt does not receive a 2xx response, Paydude automatically retries using the following schedule:
| Attempt | Delay after previous attempt | Cumulative time |
|---|---|---|
| 1 | Immediate | 0 |
| 2 | ~5 minutes | ~5 minutes |
| 3 | ~1 hour | ~1 hour |
| 4 | ~6 hours | ~7 hours |
| 5 | ~17 hours | ~24 hours |
| 6 | 12 hours | ~36 hours |
| 7 | 12 hours | ~48 hours |
| 8 | 12 hours | ~60 hours |
The first 24 hours use an accelerating backoff to handle transient outages. After that, a steady 12-hour cadence continues until all 8 attempts are exhausted (~60 hours total).
Each delivery attempt has a 5-second timeout. If your endpoint does not respond within that window, the attempt is counted as a failure and will be retried according to the schedule above.
Endpoint Health and Status
Paydude automatically monitors the health of each webhook endpoint and reduces delivery traffic to endpoints
that have stopped responding. Each endpoint has a status field with one of four values:
| Status | Description |
|---|---|
active | Normal operation. All events are delivered with the full retry schedule. |
inactive | No successful delivery has been received in 3 or more days. Events are queued but no HTTP delivery is attempted. |
pending | The endpoint has been manually re-enabled and is awaiting confirmation. Events are delivered normally. The status is promoted to active after the first successful delivery. |
disabled | No successful delivery has been received in 7 or more days. No delivery is attempted and no more events are queued for the endpoint. |
Re-enabling an inactive or disabled endpoint
To re-enable an endpoint, send a PATCH request to Update a Webhook EndpointAPI with { "status": "active" }.
The endpoint will immediately transition to pending and begin receiving events. Once a delivery is confirmed with a 2xx response, the status is automatically promoted to active.
PATCH /v1/webhook-endpoints/{id}{
"status": "active"
}If a delivery exhausts all retries while the endpoint is pending, it is immediately demoted back to inactive — a failed probation proves the endpoint is still unreachable. You will receive the same email notification as for any other inactive transition, and you can re-enable the endpoint again once you’ve resolved the issue.
Catching up on events missed while inactive
When an endpoint transitions from inactive back to pending, Paydude automatically replays every event that arrived during the outage. Replay jobs are released oldest-first with a short stagger (approximately two per second) so a recovered endpoint isn’t overwhelmed during catch-up. Events already delivered on a prior re-enable cycle are not re-delivered.
Events missed while an endpoint was disabled cannot be replayed — disabled endpoints do not record delivery attempts. Use the delivery_status=undelivered filter on List EventsAPI to see which events were skipped before they become unrecoverable.
Filtering Events by Delivery Status
The List EventsAPI endpoint supports an optional delivery_status query parameter that lets you find events based on whether they were successfully delivered.
| Value | Returns events where… |
|---|---|
succeeded | All endpoints received a 2xx response |
failed | At least one endpoint exhausted all retries without a successful delivery |
pending | The event is still queued and delivery has not yet been attempted |
undelivered | No delivery was attempted because the endpoint was inactive or disabled at the time |
This is useful for auditing missed events after re-enabling an endpoint:
GET /v1/events?delivery_status=undeliveredEmail Notifications
Paydude sends email notifications to partner account owners and admins when endpoint health changes:
- Endpoint becomes
inactive— notification includes how many days remain before the endpoint is disabled and instructions for re-enabling it. - Endpoint becomes
disabled— notification confirms the endpoint has been disabled and provides instructions for re-enabling it.
These notifications are controlled by the technical emails preference in user notification settings. Users who prefer not to receive webhook health alerts can opt out by updating their email settings.