When something happens in your account — like a payment completing, a subscription renewing, or a refund being issued — PayMongo can instantly notify your system. This is done through webhooks — automatic messages PayMongo sends to your app the moment something happens. No waiting, no manual checking.

This page walks you through setting up a webhook endpoint — the address on your server where PayMongo sends payment notifications.If you're a business owner, think of it as giving PayMongo a phone number to call whenever something happens in your account. If you're a developer, this guide covers everything from registering the endpoint to validating incoming messages.

By the end, you'll have a working endpoint ready to receive real-time updates from PayMongo.

Before you start

Make sure you have the following ready:

• A PayMongo account with access to the Dashboard.
• A publicly accessible HTTPS URL on your server that can receive POST requests
• Your PayMongo secret key (found under Developer Tools → API Keys)

Preparing your server

Your server needs a URL that:

• Accepts POST requests
• Returns an HTTP 200 response immediately upon receiving a notification
• Is accessible over HTTPS

POST https://yoursite.com/webhooks/paymongo

Test your server by sending a simple POST request. Keep your response logic simple at this stage — just return 200 to acknowledge receipt. Handle any processing logic after the acknowledgment.

Registering your webhook endpoint

There are two ways to register a webhook endpoint

• Via the Dashboard
• Via an API call

Registering through PayMongo Dashboard

Registering through PayMongo Dashboard is the most direct way to add your webhook endpoint. You can do this by:

• Log in to the PayMongo Dashboard.
• Go to Developer Tools → Webhooks.
• Click Add Endpoint.
• Enter your endpoint URL.
• Select the events you want to be notified about.
• Click Save.

Once saved, PayMongo displays your endpoint's secret key. The webhook secret key is how your server confirms that a notification genuinely came from PayMongo (See Webhook Signature Verification).

Registering via an API call

You would often opt for webhook endpoint registration via an API call over the dashboard setup when it is part of an automated process or programatic process rather than a manual one-time task.

Common scenarios where you would prefer this method would be:

• If you're building a product where each merchant or customer needs their own webhook endpoint, creating them one by one in the Dashboard isn't practical. The API lets you provision endpoints automatically when a new account is created.
• If your development team manages their environments through scripts or deployment pipelines
• If your endpoint URL changes dynamically or you need to update subscribed events based on a user's plan or settings
• Developers managing several environments (development, staging, production) can script endpoint registration for each, rather than manually repeating the same steps in the Dashboard each time.

To register a webhook endpoint via an API call, you must send a POST request to https://api.paymongo.com/v1/webhooks. The request must contain the following attributes:

curl -X POST https://api.paymongo.com/v1/webhooks \
  -H "Authorization: Basic <base64_encoded_secret_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "url": "https://yoursite.com/webhooks/paymongo",
        "events": ["payment.paid", "payment.failed"]
      }
    }
  }'

Specifying events keeps your endpoint focused — you only receive notifications that are relevant to your integration. To learn more on events and what they send you, refer to the Events section.