PayMongo HomeGuidesAPI ReferenceStart Building
Guides

Retry a Webhook Delivery

When PayMongo sends a webhook event to your endpoint, it expects a 2xx HTTP response to confirm successful delivery. If your endpoint returns a non-2xx response, PayMongo automatically retries delivery up to 12 times. If all 12 attempts fail, the delivery is marked as failed and no further automatic retries occur.

At this point, you can manually trigger a retry using the Retry a webhook process endpoint. This re-sends the original event payload to your endpoint URL, giving you one more opportunity to process it without re-creating the event.

What is a webhook process?

A webhook process is a record of a single event delivery attempt tied to a webhook endpoint. Each time PayMongo tries to send an event, a webhook process is created to track the attempt, its status, and the response received. It is distinct from the webhook endpoint, which defines where events are sent.

How automatic retries work

Before a manual retry becomes necessary, PayMongo runs through the following automatic retry sequence whenever a delivery fails.

  • Event is triggered
    An event occurs on your account (e.g., payment.paid). PayMongo creates a webhook process and attempts delivery to your endpoint URL.
  • Endpoint returns a non-2xx response
    Your endpoint responds with a status outside the 2xx range (e.g., 500, 404, 503). PayMongo marks the attempt as failed and schedules a retry.
  • Automatic retries begin
    PayMongo retries delivery automatically. This continues until the endpoint responds with a 2xx status or the maximum of 12 retry attempts is reached.
  • All 12 retries exhausted
    The webhook process is marked Failed. No further automatic retries occur. A manual retry is now required to attempt re-delivery.

When to trigger a manual retry

Trigger a manual retry when all of the following are true:

  • The webhook process status is Failed.
  • All 12 automatic retry attempts have been exhausted.
  • The downstream system or recipient did not receive or process the event.
  • You have resolved the issue on your endpoint (e.g., fixed the server error, restored connectivity) so the retry is likely to succeed.
⚠️

Resolve the root cause first

Retrying against an endpoint that is still returning errors will result in another failed delivery. Before triggering a manual retry, confirm that your endpoint is healthy and returning 2xx responses.

Retry via the Dashboard

Use the Dashboard when you need to resend a one-off failed event and prefer a visual interface. Best for non-technical team members or quick, ad hoc resends without writing any code.

Follow these steps to resend a failed webhook event from the PayMongo Dashboard. Resends are only available for enabled webhook endpoints.

  • From the left-hand navigation, select Developers, then choose Webhooks.
  • Locate the enabled webhook endpoint associated with the failed event.
  • Click on the endpoint URL to open its detail page, then select the Event Deliveries tab to view all delivery attempts for that endpoint.
  • Find the failed delivery Search for the event by Event ID or Resource ID. You can also filter by Status using the dropdown beside the Search button to narrow results to failed deliveries only.
  • Resend the event Click Resend on the delivery record.
  • A success message confirms the event has been queued for re-delivery. The resend follows the same delivery process as the original, including standard retry behavior if the resend attempt also fails.

Resends follow standard retry behavior

A resend triggered from the Dashboard is not a one-shot attempt. If your endpoint is still unhealthy and returns a non-2xx response, the standard automatic retry sequence will apply again.

Retry via API

Use the API when you need to trigger retries programmatically — for example, as part of an automated recovery workflow, monitoring script, or incident response pipeline.

Send a POST request to the retry endpoint https://api.paymongo.com/v1/webhook_processes/{id}/retry using the webhook process ID. No request body is required — the action is expressed entirely through the URL path.

curl --request POST \
  --url {{base_url}}/v1/webhook_processes/wph_xxxxxxxxxxxxxxxxxx/retry \
  --header 'accept: application/json' \
  --header 'authorization: Basic <base64-encoded-secret-key>'

Updated about 3 hours ago