Learn how to manage the lifecycle of webhook events, including marking them as processed, understanding retry logic, and retrieving missed events.
When FastSpring sends a webhook, your server must acknowledge receipt to prevent the system from resending it. This guide explains how to confirm successful delivery, how FastSpring handles failures (retries), and how to recover events that were missed.
Mark events as processed
You can mark your webhook events as processed in bulk or individually.
Return HTTP 200
Consider all received events in the payload as successfully processed.
Return HTTP 202
Apply specific requirements to individual orders. In the response body, list the ID number of the event you processed. On a new line, repeat for other IDs as necessary.
All other HTTP status codes are marked as failures. We recommend returning failed status codes in the 50X range, depending on the cause of the failure.
Retry behavior
When a webhook event is not marked as processed, FastSpring automatically retries delivery for up to 7 days from the original attempt.
Retry schedule
This pattern typically results in up to 6 retries within the first 24 hours. After the first 24 hours, the system schedules 1 retry per day, for a maximum of 12 retries within the 7-day window.
| Retry Attempt | Time until next retry |
|---|---|
0 | 1 hour after last attempt |
1 | 2 hours after last attempt |
2 | 4 hours after last attempt |
3, 4, 5 | 6 hours after last attempt |
6 + | 24 hours after last attempt |
If the event is not processed within 7 days from the original attempt, FastSpring stops retrying and marks the event as permanently failed.
Webhook log status
- Failed but will be retried: Displayed while additional retries are scheduled.
- Permanently Failed: Displayed after the 7-day window expires without a successful process.
View failed events
You can still retrieve permanently failed events from the /events API endpoint. A red Failed in last 24 hours tag appears on the card of the affected webhook event when applicable. The tag disappears when there are no failed events in the past 24 hours.
Retrieve missed or unprocessed events
If your server does not process an event successfully, you can retrieve it in any one of these ways:
- Resend it manually from the Webhook Log. Go to Developer Tools > Webhooks > Log.
- Resend it manually from the order’s details page.
- Resend it manually from the subscription’s details page.
- Make a
GETcall to the /events/unprocessed endpoint.
After you process the missed events, mark the events as processed with a POST to the /events endpoint. This prevents them from returning with future unprocessed events.
Note: We recommend setting up a scheduled task to retrieve missed webhook events automatically. After parsing the events, the script should mark them as processed.