PayMongo HomeGuidesAPI ReferenceStart Building
Guides

Setup & Management

You can register and manage webhook endpoints through the PayMongo Dashboard or directly via the API. Both methods give you full control over your endpoints — use whichever fits your workflow.

Authenticating API requests to manage webhooks

Before PayMongo can send payment notifications to your system, you need to register a webhook — telling PayMongo where to send those notifications and which events to listen for. That registration is done through the PayMongo API, and like all API requests, it requires authentication.

Your API secret key

PayMongo provides two types of API keys for each account: a test key and a live key. Both follow the same format but serve different purposes.

  • Test key (sk_test_...) — used during development and testing. Requests made with this key interact with PayMongo's test environment, where no real money is involved.
  • Live key (sk_live_...) — used in your production environment. Requests made with this key affect your real PayMongo account and real transactions.

Your API keys are available in the Developers section of your PayMongo Dashboard.

Keep your secret keys private. Anyone with access to your sk_live_ key can make API calls on behalf of your account, including creating or modifying webhooks. Never expose these keys in client-side code, public repositories, or anywhere a customer could see them.

Via the dashboard

  • Go to Developers → Webhooks in the Dashboard.
  • Click Add endpoint.
  • Enter your endpoint URL and select the events you want to listen to.
  • Click Save. PayMongo will begin sending matching events to your endpoint immediately.

Via the API

Send a POST request to /v1/webhooks with your endpoint URL and the list of events to subscribe to.

{
  "data": {
    "attributes": {
      "url": "https://example.com/webhook",
      "events": ["payment.paid", "payment.failed"]
    }
  }
}

A successful request returns a webhook object containing your endpoint ID. Keep this — you'll need it to update or disable the endpoint later.

Updating an endpoint

To change the URL or the events an endpoint listens to, send a PUT request to /v1/webhooks/{id} with the fields you want to update.

You can also update an endpoint from the Dashboard by going to Developers → Webhooks, selecting the endpoint, and editing its details.

Disabling an endpoint

Disabling an endpoint stops PayMongo from sending events to it without deleting the endpoint or its configuration.

Via the dashboard

Go to Developers → Webhooks, select the endpoint, and toggle it off.

Via the API

  • Send a POST request to /v1/webhooks/{id}/disable.
  • Disabled endpoints retain their configuration and event history.
    • No events are delivered while an endpoint is disabled, and missed events are not replayed when the endpoint is re-enabled.

Re-enabling an endpoint

To resume event delivery to a disabled endpoint, send a POST request to /v1/webhooks/{id}/enable, or toggle it back on from the Dashboard.

Listing your endpoints

To retrieve all registered webhook endpoints on your account, send a GET request to /v1/webhooks. The response returns a list of webhook objects with their current status, subscribed events, and endpoint URLs.

Securing a webhook

Exposing an API endpoint on your server can pose security risks if not properly secured. Unauthorized parties could attempt to access the endpoint to retrieve data, modify it, or overload your server.

To help prevent this, PayMongo includes a Paymongo-Signature HTTP header in every webhook request. You can use this header to verify that the request genuinely came from PayMongo.

Below is a sample Paymongo-Signature header:

t=1496734173,te=1447a89e7ecebeda32sffs62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd,li=
t=1492224173,te=,li=3f7bs59d200aae63f272406069a9788598b792a944a07aba816edb039989a39

The Paymongo-Signature header consists of three comma-separated parts:

  1. t - the timestamp of the request
  2. te - the signature for test mode
  3. li - the signature for live mode

To verify the request, generate your signature using the webhook's secret key and compare it to the appropriate value: use te for test mode events and li for live mode events.

  1. Parse the Paymongo-Signature header. Split the header by commas to extract three parts: t, te, and li
  2. Create the signature string. Concatenate the following in order:
    1. The timestamp (t) as a string (e.g., 1496734173)
    2. A . character (period)
    3. The raw JSON payload of the request. Ensure you use the raw request body, not the parsed or formatted version. Refer to your framework's documentation for retrieving the raw payload.
  3. Generate the HMAC. Use the SHA-256 hash function with your webhook's secret key as the HMAC key to hash the string from step 2.
  4. Compare the signature. Use li for live mode events. Use te for test mode events. If the signature you computed does not match the one provided, discard the request; it did not come from PayMongo.

For added security, you can compare the timestamp in the header with the current time. If the difference is too large, the request may be outdated or a replay attack. This step is optional but recommended.

Updated about 3 hours ago