Webhook Implementation Best Practices

Overview

To help your system process webhook events efficiently and securely, we recommend following these key best practices:

1. Use HTTPS with a Valid SSL Certificate. Your webhook URL must use HTTPS with a valid, publicly trusted SSL certificate. This ensures secure data delivery and prevents man-in-the-middle attacks or tampering. Webhook delivery will fail if your endpoint is not HTTPS or uses a self-signed or expired certificate.
   

2. Respond Immediately with HTTP 2xx. Always return an HTTP 2xx status (e.g., 200 OK) as soon as you receive the webhook event. This signals to PayMongo that you’ve accepted the event. Perform any further processing (database updates, notifications) after sending this response to avoid timeouts and duplicate retries.
   

3. Log and Monitor Events. Keep logs of all webhook events for debugging and audit trails. Set up monitoring and alerts for failures or unexpected responses so your team can address issues promptly.
   

4. Reconcile Missed Events via API. If your webhook endpoint is temporarily unavailable, use the PayMongo API to retrieve the Payment Intent and check transaction status as a fallback.
   

5. Verify the Paymongo-Signature Header (Optional but Recommended). Verify the Paymongo-Signature header on each webhook request to confirm it originated from PayMongo. See our Securing a Webhook section for detailed instructions.