Key Concepts

What is a webhook?

A webhook is an HTTP endpoint — a URL on your server — that PayMongo calls when an event occurs. You register the URL with PayMongo, and PayMongo sends a POST request to it every time a matching event happens. Think of it as a doorbell: instead of you constantly checking whether someone is at the door, PayMongo rings it for you.

Events

Everything that happens on PayMongo is represented as an event. An event has:

• A type — a dot-separated string describing what happened (e.g., payment.paid, refund.created).
• A data object — the full resource snapshot at the time of the event.
• A timestamp — when the event was created.

Events are immutable. PayMongo never modifies an event after it is created.

Webhook endpoints

A webhook endpoint is the URL you register with PayMongo to receive events. You can register multiple endpoints — for example, one for your order management system and another for your analytics pipeline. Each endpoint can be configured to receive all events or a filtered subset.

Delivery

When an event fires, PayMongo sends an HTTP POST to each registered endpoint. The request body contains the full event payload in JSON. Your endpoint must respond with an HTTP status code between 200 and 209, along with a JSON response within 30 seconds to be considered a successful delivery.

If delivery fails — due to a timeout, a non-2xx response, or a network error — PayMongo retries automatically up to 12 times using exponential backoff. See Retry Logic for the full retry schedule.

Webhook secret and signature

Every webhook endpoint has a secret key. PayMongo signs each request with this secret and includes the signature in the Paymongo-Signature header. Verifying this signature in your handler confirms the request genuinely came from PayMongo. See Best Practices for how to verify signatures.

Test mode vs. live mode

Webhook endpoints are scoped to the mode — test or live — in which they are created. Test-mode endpoints only receive events generated by test-mode API keys; live-mode endpoints only receive live events. Register separate endpoints for each environment.