Webhooks

Webhooks allow you to receive real-time notifications when payment events occur. PayMongo sends webhook events to inform you about donation status changes.

Overview

Instead of polling the API to check donation status, configure webhooks to receive automatic notifications when:

Payment is completed
Payment fails

Benefits

Name
Real-time Updates
Description
Get instant notifications without polling
Name
Reduced API Calls
Description
No need to constantly check donation status
Name
Reliable
Description
Payment gateways retry failed webhook deliveries
Name
Automatic
Description
Updates happen in the background without user action

Webhook Endpoints

Batchmates provides a dedicated webhook endpoint for the payment gateway:

Name
PayMongo Webhook
Description
POST https://batchmates-v2.revlv.com/api/v1/payments/paymongo/webhook

PayMongo Webhooks

Webhook Events

PayMongo sends the following events:

Name
checkout_session.payment.paid
Description
Hosted checkout payment completed successfully (primary completion signal)
Name
payment.paid
Description
Payment completed; marks the donation completed if resolvable, otherwise logged and skipped
Name
payment.failed
Description
Payment failed (insufficient funds, declined card, etc.)

Payload Structure

{
  "data": {
    "id": "evt_abc123",
    "attributes": {
      "type": "checkout_session.payment.paid",
      "data": {
        "id": "cs_abc123",
        "attributes": {
          "reference_number": "550e8400-e29b-41d4-a716-446655440000",
          "metadata": { "donation_reference": "550e8400-e29b-41d4-a716-446655440000" },
          "payments": [{ "attributes": { "status": "paid", "source": { "type": "gcash" } } }]
        }
      }
    }
  }
}

Example: Payment Success

PayMongo Webhook - Payment Success

{
  "data": {
    "id": "evt_abc123xyz",
    "attributes": {
      "type": "checkout_session.payment.paid",
      "data": {
        "id": "cs_abc123xyz",
        "attributes": {
          "reference_number": "550e8400-e29b-41d4-a716-446655440000",
          "payments": [{ "attributes": { "status": "paid", "amount": 103730, "source": { "type": "gcash" } } }]
        }
      }
    }
  }
}

What happens:

PayMongo sends webhook to your endpoint
Batchmates verifies the Paymongo-Signature header
Donation status updated to completed
Campaign raised_amount and available_amount incremented
User receives success notification

Example: Payment Failed

PayMongo Webhook - Payment Failed

{
  "data": {
    "id": "evt_def456abc",
    "attributes": {
      "type": "payment.failed",
      "data": {
        "id": "pi_def456abc",
        "attributes": {
          "reference_number": "650e8400-e29b-41d4-a716-446655440001",
          "last_payment_error": { "failed_message": "Insufficient funds" }
        }
      }
    }
  }
}

What happens:

PayMongo sends webhook
Donation status updated to failed
User can retry payment from their donation history

Webhook Security

PayMongo's webhook endpoint is protected by HMAC signature verification — every request is signed and the signature is checked before the handler runs.

Paymongo-Signature: t=,te=,li=

Which signature is checked depends on PAYMONGO_LIVEMODE (te when false, li when true). Requests older than 5 minutes are rejected as replays.

Batchmates API automatically handles webhook verification. You don't need to implement this unless building your own webhook handlers.

Testing Webhooks

Using Webhook Testing Tools

1. ngrok for Local Development

# Install ngrok
brew install ngrok  # macOS
# or download from ngrok.com

# Start your local server
php artisan serve

# Expose port 8000
ngrok http 8000

# Use the ngrok URL in your PayMongo dashboard webhook config
# https://abc123.ngrok.io/api/v1/payments/paymongo/webhook

2. RequestBin for Quick Testing

# Create a RequestBin at requestbin.com
# Use the bin URL to inspect webhook payloads

Manual Webhook Testing

Test PayMongo Webhook

curl -X POST https://batchmates-v2.revlv.com/api/v1/payments/paymongo/webhook \
  -H "Content-Type: application/json" \
  -H "Paymongo-Signature: t={timestamp},te={computed_signature}" \
  -d '{
    "data": {
      "id": "evt_test_123",
      "attributes": {
        "type": "checkout_session.payment.paid",
        "data": { "id": "cs_test_123", "attributes": { "reference_number": "550e8400-e29b-41d4-a716-446655440000" } }
      }
    }
  }'

Webhook Flow Diagram

Complete Payment Flow

sequenceDiagram
    participant User
    participant App
    participant API
    participant Gateway

    User->>App: Click "Donate"
    App->>API: POST /donations
    API->>Gateway: Create checkout
    Gateway-->>API: Checkout URL
    API-->>App: Redirect URL
    App->>Gateway: Redirect to payment
    User->>Gateway: Enter payment details
    Gateway->>Gateway: Process payment
    Gateway->>API: Webhook: checkout_session.payment.paid
    API->>API: Update donation status
    API->>API: Update campaign balances
    API->>User: Send notification
    Gateway->>User: Redirect to success page
    User->>App: View success page

Webhook Event Reference

PayMongo Events

Event	Description	Action
checkout_session.payment.paid	Payment completed	Mark donation completed
payment.paid	Payment completed (saved-card / intent charges)	Mark donation completed if resolvable
payment.failed	Payment failed	Mark donation failed

Troubleshooting

Webhook Not Received

Check:

Webhook URL configured correctly in gateway dashboard
Server is publicly accessible (not behind firewall)
HTTPS enabled (required by most gateways)
No rate limiting blocking webhook requests

Webhook Rejected

Check:

Paymongo-Signature header present and not malformed
The correct signing secret is configured for the mode (te/li) currently in use
Request is not older than 5 minutes (replay protection)
No proxy is rewriting the request body — signature verification hashes the raw body

Donation Not Updating

Check:

Webhook handler returns 200 OK
Reference number matches donation record
Idempotency checks not blocking legitimate updates
Database transaction not rolled back due to error

Testing Webhooks

# Check if webhook endpoint is accessible
curl -I https://batchmates-v2.revlv.com/api/v1/payments/paymongo/webhook

# Should return 405 Method Not Allowed (POST required)
# If timeout or connection error, check firewall/DNS

Need Help?

If webhooks aren't working as expected:

Check webhook logs in payment gateway dashboard
Verify webhook URL configuration
Test with manual webhook calls
Review signature verification implementation
Contact support with webhook payload and error logs

Contact Support Donations API