Webhook

A Webhook is a URL where we send real-time event notifications related to your account. For practical examples and use cases, please refer to the webhook section in our integration guide.

❗️
Your server must return an HTTP status code between 200 and 209, along with a JSON response, to acknowledge the event.
PayMongo retries each failed webhook delivery up to 12 times. If 3 consecutive events each exhaust all 12 retries without a successful response, your webhook is automatically disabled. To resume receiving events, re-enable the webhook manually.

📘
Note
Merchants should implement a rollback mechanism to handle cases when their webhook URL or server is unavailable. PayMongo does not re-send missed webhook events, so it's crucial to design your system to handle interruptions and process events once your webhook URL is back online.
As a rollback mechanism, we suggest retrieving a payment intent by ID to check the status of a transaction.

Webhook Resource

{
    "data": {
        "id": "hook_UD3rYjZ74dB9WUNNvJnpAuLu",
        "type": "webhook",
        "attributes": {
            "events": [
	              "payment.failed",
                "payment.paid"
            ],
            "livemode": true,
            "secret_key": "whsk_24usnQXfHAzo1AFXspLmD1R4",
            "status": "enabled",
            "url": "http://google.com/webhook",
            "created_at": 1747071097,
            "updated_at": 1747071097
        }
    }
}

id string
Unique ID of the resource.

type string
Represents the resource type. This value is always set to webhook.

disabled_reason string
Indicates why the webhook was disabled. This field is returned only when the webhook is disabled. Possible values are: disabled_by_merchant - The webhook was manually disabled by the merchant. max_retries_exceeded - The webhook was automatically disabled after exceeding the maximum number of retry attempts.

events array of strings
The list of events to be sent to this webhook. Possible values in the meantime are:

Checkout transactions: checkout_session.payment.paid

Transactions: source.chargeable, payment.paid, and payment.failed

Refunds: payment.refunded and payment.refund.updated

Subscriptions: subscription.past_due, subscription.unpaid, and subscription.updated

Invoices: subscription.invoice.created, subscription.invoice.finalized, subscription.invoice.paid, and subscription.invoice.payment_failed

PayMongo Links: link.payment.paid

QR Ph codes: qrph.expired

Merchant: merchant.activated, merchant.declined

Consumer: consumer.activated, consumer.declined

Accounts: accounts.identity_verifications.passed, accounts.identity_verifications.failed

livemode boolean
The value is true if the resource exists in live mode or the value is false if the resource exists in test mode.

secret_key string
The secret key is a string used to generate a signature that verifies the authenticity of webhook events, helping to secure your integration. For more details, refer to the Webhooks section of our integration guide.

status string
An enabled webhook actively receives event notifications, while a disabled webhook does not.

url string
The destination URL of the events that happened from your account. Please ensure that the URL is publicly accessible so that you can receive the event.

created_at timestamp
The timestamp when the webhook was created.

updated_at timestamp
The timestamp when the webhook was updated.