Webhook Implementation Best Practices

To ensure your system handles webhook events efficiently and securely, here are some key practices we recommend:

1. Use HTTPS with a Valid SSL Certificate
   Webhook URLs must be served over HTTPS and have a valid, publicly trusted SSL certificate. This ensures secure delivery and helps prevent man-in-the-middle attacks or tampering. If your endpoint is not accessible via HTTPS or uses a self-signed or expired certificate, webhook delivery will fail.
   
   

2. Ensure Your Endpoint Responds with HTTP 2xx
   Your webhook endpoint must return an HTTP 2xx status code (e.g., 200 OK) as soon as it receives the event. This tells PayMongo that your system has accepted the webhook.
   
   Even if further processing is needed (like updating your database or triggering notifications), do it after sending the 2xx response to avoid timeouts and duplicate retries.
   
   

3. Log and Monitor Events
   Log all received webhook events for debugging and traceability. Set up alerts to monitor for failures or unexpected status codes so your team can respond promptly to issues.
   
   

4. Reconcile Missed Events
   If your webhook URL becomes temporarily unavailable, you can use the PayMongo API as a rollback mechanism by retrieving the Payment Intent to determine the status of the transaction.
   
   

5. (Optional) Secure Your Webhook
   To protect your endpoints from unauthorized requests, verify the Paymongo-Signature header in each request. This helps confirm that the webhook is genuinely from PayMongo. Refer to our Securing a Webhook section for full implementation details.