Payment Webhook

Overview

The payment webhook endpoint receives notifications from MercadoPago when payment events occur. It automatically activates user subscriptions, creates audit logs, and handles idempotent processing to prevent duplicate activations.

This endpoint is implemented as a Cloudflare Worker for high reliability and low latency processing of payment notifications.

Endpoint

POST https://mercadopago-jcv.fagal142010.workers.dev/webhook
POST https://mercadopago-jcv.fagal142010.workers.dev/api/webhooks/mercadopago

Authentication

The webhook is called directly by MercadoPago. No authentication headers are required from the client, but the worker:

Validates the payment ID with MercadoPago API
Uses MercadoPago’s API to fetch payment details
Implements idempotency checks to prevent duplicate processing

Security: The webhook URL should be registered in your MercadoPago account settings. Do not expose the webhook endpoint publicly as it can create subscriptions.

Webhook Payload

MercadoPago sends notifications in the following format:

type

string

required

Notification type. Must be payment for payment events.

action

string

required

Event action. Typically payment.created or payment.updated.

data

object

required

Payment data object

Show Data Properties

string

required

MercadoPago payment ID to fetch full payment details

Example Webhook Payload

{
  "action": "payment.updated",
  "api_version": "v1",
  "data": {
    "id": "1234567890"
  },
  "date_created": "2024-03-01T10:00:00Z",
  "id": 12345,
  "live_mode": true,
  "type": "payment",
  "user_id": "123456789"
}

Processing Flow

The webhook processes payments through the following steps:

1. Receive & Log

Every webhook notification is immediately logged to the webhook_logs table with status received.

2. Validate Event Type

Only payment type notifications with actions payment.created or payment.updated are processed. Other notifications are logged and ignored.

3. Idempotency Check

The webhook checks if the same payment_id + action combination was already successfully processed. If yes, it returns success without creating duplicate subscriptions.

4. Fetch Payment Details

The worker fetches full payment details from MercadoPago API:

GET https://api.mercadopago.com/v1/payments/{payment_id}
Authorization: Bearer {MP_ACCESS_TOKEN}

5. Validate Payment Status

Only payments with status approved proceed to subscription activation. Other statuses are logged for monitoring.

6. User Lookup

The webhook attempts to find the user through multiple methods:

Metadata User ID

Check if metadata.user_id exists in the payment

External Reference

Extract user ID from external_reference (format: JCV-timestamp-userId)

Payer Email

Look up user by payer.email in the profiles table

7. Plan Detection

The plan type is determined from the payment amount:

Amount (COP)	Plan Type	Duration
49,900	PLAN_BASICO	40 days
89,900	PLAN_PRO	40 days
149,900	PLAN_PREMIUM	40 days

If the amount doesn’t match, it falls back to metadata.plan_type or defaults to PLAN_BASICO.

8. Subscription Creation

The webhook creates a new subscription in Supabase:

INSERT INTO subscriptions (
  user_id,
  plan_type,
  status,
  start_date,
  end_date,
  payment_provider,
  payment_reference,
  amount_paid
)

9. Profile Update

Updates the user’s profile with active subscription information:

UPDATE profiles SET
  has_active_subscription = true,
  current_plan = 'PLAN_PRO',
  subscription_end_date = '2024-04-10T10:00:00Z'
WHERE id = user_id

10. Audit Log

Creates an entry in subscription_audit_log for compliance and debugging:

{
  "subscription_id": "sub-uuid",
  "user_id": "user-uuid",
  "operation": "activated",
  "trigger_source": "webhook",
  "trigger_reference": "1234567890",
  "metadata": {
    "webhook_log_id": "log-uuid",
    "user_lookup_method": "payer_email",
    "payment_status": "approved"
  }
}

Response

Success Response

received

boolean

Always true when webhook is received

processed

boolean

true if subscription was activated, false if ignored

subscription

object

Subscription activation details

Show Subscription Properties

status

string

Either activated or already_exists

subscription_id

string

UUID of the created or existing subscription

user_id

string

UUID of the user

plan_type

string

Plan type (e.g., PLAN_PRO)

expires

string

ISO 8601 timestamp when subscription expires

log_id

string

UUID of the webhook log entry for debugging

Example Success Response

{
  "received": true,
  "processed": true,
  "subscription": {
    "status": "activated",
    "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "7b9e6f12-3c45-4a21-8e9d-1234567890ab",
    "plan_type": "PLAN_PRO",
    "expires": "2024-04-10T10:00:00.000Z"
  },
  "log_id": "6a8d5c21-4b32-4f18-9c8e-0987654321ba"
}

Ignored Response

Returned when the webhook is received but not processed:

{
  "received": true,
  "ignored": true,
  "reason": "non-payment",
  "log_id": "webhook-log-uuid"
}

{
  "received": true,
  "duplicate": true,
  "original_log_id": "original-log-uuid",
  "log_id": "current-log-uuid"
}

Error Handling

The webhook implements intelligent error handling with retry logic:

Error Types

CONFIG_ERROR - Configuration Error

Should Retry: NoStatus Code: 500Cause: Missing environment variables (MP_ACCESS_TOKEN, SUPABASE_URL, SUPABASE_SERVICE_KEY)Action: Fix server configuration and redeploy

AUTH_ERROR - Authentication Error

Should Retry: NoStatus Code: 200 (to prevent MercadoPago retries)Cause: Invalid or expired MercadoPago access tokenAction: Update MP_ACCESS_TOKEN in environment variables

NOT_FOUND - Payment Not Found

Should Retry: NoStatus Code: 200 (to prevent MercadoPago retries)Cause: Payment ID doesn’t exist in MercadoPagoAction: Investigate if payment was deleted or notification is invalid

VALIDATION_ERROR - Data Validation Error

Should Retry: NoStatus Code: 200Cause: User not found, invalid payment dataAction: Check that user exists before payment or fix data mapping

NETWORK_ERROR - Network Error

Should Retry: YesStatus Code: 500Cause: DNS failure, timeout, connection refusedAction: MercadoPago will automatically retry

RATE_LIMIT - Rate Limit Exceeded

Should Retry: YesStatus Code: 500Cause: Too many requests to MercadoPago APIAction: Wait and retry, MercadoPago will handle retry logic

SERVER_ERROR - Server Error

Should Retry: YesStatus Code: 500Cause: MercadoPago API or Supabase temporary errorAction: MercadoPago will automatically retry

Retry Strategy

MercadoPago automatically retries webhook deliveries for 48 hours when it receives a 5xx response or connection failure. The webhook returns 200 for permanent errors (AUTH, NOT_FOUND, VALIDATION) to prevent unnecessary retries.

Webhook Logs

All webhook notifications are logged to the webhook_logs table:

Column	Description
`id`	UUID primary key
`status`	`received`, `processing`, `success`, `failed`, `ignored`
`webhook_type`	Event type from MercadoPago
`webhook_action`	Action type (payment.created, payment.updated)
`payment_id`	MercadoPago payment ID
`payment_status`	Payment status (approved, pending, rejected)
`payment_amount`	Payment amount
`user_email`	Payer’s email
`user_id`	JCV Fitness user UUID
`subscription_id`	Created subscription UUID
`plan_type`	Activated plan type
`is_duplicate`	Boolean flag for duplicate webhooks
`error_message`	Error message if failed
`processing_time_ms`	Processing duration in milliseconds
`supabase_operations`	JSON array of database operations
`raw_payload`	Full webhook payload
`received_at`	Webhook received timestamp
`processed_at`	Processing completed timestamp

Health Check

The webhook endpoint supports health checks:

GET https://mercadopago-jcv.fagal142010.workers.dev/webhook

Response:

{
  "status": "ok",
  "service": "mercadopago-webhook"
}

Webhook Flow Diagram

Configuring the Webhook in MercadoPago

Access MercadoPago Dashboard

Go to MercadoPago Developers

Navigate to Webhooks

In your application settings, find the “Webhooks” or “Notifications” section

Add Production URL

Enter the webhook URL:

https://mercadopago-jcv.fagal142010.workers.dev/webhook

Select Events

Subscribe to these events:

payment.created
payment.updated

Test Webhook

Use MercadoPago’s webhook testing tool to send a test notification

Testing

Manual Testing

You can manually trigger the webhook using curl:

curl -X POST https://mercadopago-jcv.fagal142010.workers.dev/webhook \
  -H "Content-Type: application/json" \
  -d '{
    "type": "payment",
    "action": "payment.updated",
    "data": {
      "id": "1234567890"
    }
  }'

Monitoring Webhooks

Query the webhook logs to monitor webhook processing:

SELECT 
  id,
  status,
  payment_id,
  payment_status,
  user_email,
  plan_type,
  processing_time_ms,
  error_message,
  received_at,
  processed_at
FROM webhook_logs
ORDER BY received_at DESC
LIMIT 50;

Common Issues

User not found error

Cause: User doesn’t exist in database when payment is madeSolution: Ensure users are created before initiating payment, or implement auto-registration based on payer email

Duplicate subscriptions

Cause: Multiple webhooks for the same paymentSolution: The webhook has built-in idempotency - check is_duplicate flag in logs

Wrong plan type

Cause: Payment amount doesn’t match PLAN_CONFIGSolution: Update PLAN_CONFIG in worker or ensure correct amount is sent

Security Considerations

Signature Verification: Currently, the webhook validates payments by fetching from MercadoPago API. For additional security, consider implementing signature verification using x-signature header.

IP Whitelisting: Consider adding Cloudflare Workers firewall rules to only accept webhooks from MercadoPago’s IP ranges.

Create Payment Preference

Create MercadoPago payment preferences

Authentication

Subscriptions

Plans

Payments

Overview

Endpoint

Authentication

Webhook Payload

Example Webhook Payload

Processing Flow

1. Receive & Log

2. Validate Event Type

3. Idempotency Check

4. Fetch Payment Details

5. Validate Payment Status

6. User Lookup

7. Plan Detection

8. Subscription Creation

9. Profile Update

10. Audit Log

Response

Success Response

Example Success Response

Ignored Response

Error Handling

Error Types

Retry Strategy

Webhook Logs

Health Check

Webhook Flow Diagram

Configuring the Webhook in MercadoPago

Testing

Manual Testing

Monitoring Webhooks

Common Issues

Security Considerations

Create Payment Preference

Additional Resources

Build docs developers (and LLMs) love

Authentication

Subscriptions

Plans

Payments

​Overview

​Endpoint

​Authentication

​Webhook Payload

​Example Webhook Payload

​Processing Flow

​1. Receive & Log

​2. Validate Event Type

​3. Idempotency Check

​4. Fetch Payment Details

​5. Validate Payment Status

​6. User Lookup

​7. Plan Detection

​8. Subscription Creation

​9. Profile Update

​10. Audit Log

​Response

​Success Response

​Example Success Response

​Ignored Response

​Error Handling

​Error Types

​Retry Strategy

​Webhook Logs

​Health Check

​Webhook Flow Diagram

​Configuring the Webhook in MercadoPago

​Testing

​Manual Testing

​Monitoring Webhooks

​Common Issues

​Security Considerations

​Related Endpoints

Create Payment Preference

​Additional Resources

Build docs developers (and LLMs) love

Overview

Endpoint

Authentication

Webhook Payload

Example Webhook Payload

Processing Flow

1. Receive & Log

2. Validate Event Type

3. Idempotency Check

4. Fetch Payment Details

5. Validate Payment Status

6. User Lookup

7. Plan Detection

8. Subscription Creation

9. Profile Update

10. Audit Log

Response

Success Response

Example Success Response

Ignored Response

Error Handling

Error Types

Retry Strategy

Webhook Logs

Health Check

Webhook Flow Diagram

Configuring the Webhook in MercadoPago

Testing

Manual Testing

Monitoring Webhooks

Common Issues

Security Considerations

Related Endpoints

Additional Resources