Webhooks API

Overview

The Webhooks API endpoint receives and validates notifications from Mercado Pago about events such as payment updates, refunds, and other transaction-related activities. This endpoint is always active and is the primary way to receive real-time updates from Mercado Pago.

Unlike other demo endpoints, the webhook endpoint is always active in all environments and is essential for production use.

Receive Webhook

Receives and processes webhook notifications from Mercado Pago.

Endpoint

POST /api/mercadopago/webhooks

Request Headers

x-signature

string

HMAC signature for webhook validation. Format: ts={timestamp},v1={hash}

Required when MERCADOPAGO_WEBHOOK_SECRET is configured. Used to verify the authenticity of the webhook.

x-request-id

string

Unique request identifier from Mercado Pago. Required for signature validation.

Query Parameters

string

Resource ID (alternative to data.id in body)

topic

string

Notification topic (alternative to type in body)

Request Body Parameters

action

string

Action that triggered the notification (e.g., “payment.created”, “payment.updated”)

api_version

string

Mercado Pago API version

type

string

Notification type/topic (e.g., “payment”, “merchant_order”)

data

object

Notification data object

Show Data properties

data.id

string

ID of the resource that triggered the notification

live_mode

boolean

Whether the notification is from production (true) or sandbox (false)

user_id

string

Mercado Pago user ID

Request Example

{
  "action": "payment.updated",
  "api_version": "v1",
  "type": "payment",
  "data": {
    "id": "1234567890"
  },
  "live_mode": true,
  "user_id": "987654321"
}

Response

boolean

Indicates if the webhook was received successfully

data

object

Processed webhook information

Show Webhook response properties

acknowledged

boolean

Whether the webhook was acknowledged

validated

boolean

Whether the webhook signature was validated

Will be false if MERCADOPAGO_WEBHOOK_SECRET is not configured

topic

string

Notification topic (e.g., “payment”, “merchant_order”)

resource

string

Resource ID that triggered the notification

payload

object

Complete webhook payload received

Response Example

{
  "ok": true,
  "data": {
    "acknowledged": true,
    "validated": true,
    "topic": "payment",
    "resource": "1234567890",
    "payload": {
      "action": "payment.updated",
      "api_version": "v1",
      "type": "payment",
      "data": {
        "id": "1234567890"
      },
      "live_mode": true,
      "user_id": "987654321"
    }
  },
  "meta": []
}

cURL Example

curl --request POST \
  --url http://localhost:8000/api/mercadopago/webhooks \
  --header 'Content-Type: application/json' \
  --header 'x-signature: ts=1234567890,v1=abcdef123456' \
  --header 'x-request-id: unique-request-id' \
  --data '{
    "type": "payment",
    "data": {
      "id": "123"
    }
  }'

Error Responses

Invalid Signature (401)

{
  "ok": false,
  "message": "Invalid webhook signature"
}

General Error (500)

{
  "ok": false,
  "message": "Error message describing what went wrong"
}

Signature Validation

When MERCADOPAGO_WEBHOOK_SECRET is configured, the package validates the webhook signature to ensure authenticity.

Validation Process

Extract ts (timestamp) and v1 (hash) from x-signature header
Get x-request-id from headers
Get resource id from query string or request body data.id
Construct manifest: id={id}&request-id={request-id}&ts={ts}
Compute HMAC-SHA256 hash using webhook secret
Compare computed hash with provided v1 hash

Production Requirement: Always configure MERCADOPAGO_WEBHOOK_SECRET in production to ensure webhook authenticity and prevent unauthorized notifications.

Signature Header Format

x-signature: ts=1234567890,v1=abc123def456...

Implementation Notes

Availability

The webhook endpoint is always active regardless of environment or demo route settings. This is necessary to receive production notifications.

Controller Reference

Implemented in: src/Http/Controllers/Api/WebhookController.php:13 Request validation: src/Http/Requests/StoreWebhookRequest.php:16

WebhookService - Service layer for webhook processing and validation

Webhook Integration - Complete guide on webhook setup
Webhook Security - Security best practices for webhooks

Webhook Topics

Mercado Pago sends notifications for various events:

Topic	Description
`payment`	Payment created, updated, or cancelled
`merchant_order`	Order created or updated
`subscription`	Subscription events
`point_integration_wh`	Point of sale integration events

Best Practices

Idempotency: Mercado Pago may send duplicate notifications. Always check if you’ve already processed a notification before taking action.

Async Processing: Process webhook notifications asynchronously using queued jobs. Return a 200 response quickly to avoid timeouts.

Verify Resource: Always fetch the actual resource from Mercado Pago to verify its current state. Don’t rely solely on webhook data for critical operations.

Recommended Workflow

Receive webhook → Return 200 immediately
Validate signature → If configured
Dispatch job → Process asynchronously
Fetch resource → Get current state from Mercado Pago
Update database → Persist the current state
Trigger actions → Send emails, update orders, etc.

Example Production Implementation

use Fitodac\LaravelMercadoPago\Services\WebhookService;
use Fitodac\LaravelMercadoPago\Services\PaymentService;

final class MercadoPagoWebhookController
{
    public function handle(
        Request $request,
        WebhookService $webhookService,
        PaymentService $paymentService
    ): JsonResponse {
        // Validate webhook
        $webhook = $webhookService->handle($request);
        
        if (!$webhook['validated']) {
            return response()->json(['error' => 'Invalid signature'], 401);
        }
        
        // Dispatch async job
        if ($webhook['topic'] === 'payment') {
            ProcessPaymentWebhook::dispatch($webhook['resource']);
        }
        
        return response()->json(['ok' => true]);
    }
}

Example Queued Job

use Fitodac\LaravelMercadoPago\Services\PaymentService;

final class ProcessPaymentWebhook implements ShouldQueue
{
    public function __construct(private string $paymentId) {}
    
    public function handle(PaymentService $paymentService): void
    {
        // Fetch current payment state
        $payment = $paymentService->get($this->paymentId);
        
        // Check if already processed
        $localPayment = Payment::where('mercadopago_id', $this->paymentId)->first();
        
        if ($localPayment && $localPayment->status === $payment['status']) {
            return; // Already processed
        }
        
        // Update local database
        $localPayment->update([
            'status' => $payment['status'],
            'status_detail' => $payment['status_detail'],
        ]);
        
        // Trigger business logic based on status
        if ($payment['status'] === 'approved') {
            // Send confirmation email, fulfill order, etc.
        }
    }
}

Configuration

Required Environment Variables

# Required for webhook validation
MERCADOPAGO_WEBHOOK_SECRET=your_webhook_secret_here

Configuring in Mercado Pago

Go to your Mercado Pago dashboard
Navigate to Developers → Webhooks
Add your webhook URL: https://your-domain.com/api/mercadopago/webhooks
Copy the Secret and set it as MERCADOPAGO_WEBHOOK_SECRET
Select the events you want to receive

Testing Webhooks

Local Testing

Use a tunneling service (ngrok, expose, etc.) to expose your local server:

ngrok http 8000

Configure the public URL in Mercado Pago’s webhook settings
Trigger test events from Mercado Pago dashboard or by performing test transactions

Manual Testing

curl --request POST \
  --url http://localhost:8000/api/mercadopago/webhooks \
  --header 'Content-Type: application/json' \
  --data '{
    "type": "payment",
    "data": {"id": "123"}
  }'

When testing locally without MERCADOPAGO_WEBHOOK_SECRET, the webhook will be processed but validated will be false.

Services

Demo Endpoints

Configuration

Overview

Receive Webhook

Endpoint

Request Headers

Query Parameters

Request Body Parameters

Request Example

Response

Response Example

cURL Example

Error Responses

Invalid Signature (401)

General Error (500)

Signature Validation

Validation Process

Signature Header Format

Implementation Notes

Availability

Controller Reference

Webhook Topics

Best Practices

Recommended Workflow

Example Production Implementation

Example Queued Job

Configuration

Required Environment Variables

Configuring in Mercado Pago

Testing Webhooks

Local Testing

Manual Testing

Build docs developers (and LLMs) love

Services

Demo Endpoints

Configuration

​Overview

​Receive Webhook

​Endpoint

​Request Headers

​Query Parameters

​Request Body Parameters

​Request Example

​Response

​Response Example

​cURL Example

​Error Responses

​Invalid Signature (401)

​General Error (500)

​Signature Validation

​Validation Process

​Signature Header Format

​Implementation Notes

​Availability

​Controller Reference

​Related Services

​Related Guides

​Webhook Topics

​Best Practices

​Recommended Workflow

​Example Production Implementation

​Example Queued Job

​Configuration

​Required Environment Variables

​Configuring in Mercado Pago

​Testing Webhooks

​Local Testing

​Manual Testing

Build docs developers (and LLMs) love

Overview

Receive Webhook

Endpoint

Request Headers

Query Parameters

Request Body Parameters

Request Example

Response

Response Example

cURL Example

Error Responses

Invalid Signature (401)

General Error (500)

Signature Validation

Validation Process

Signature Header Format

Implementation Notes

Availability

Controller Reference

Related Services

Related Guides

Webhook Topics

Best Practices

Recommended Workflow

Example Production Implementation

Example Queued Job

Configuration

Required Environment Variables

Configuring in Mercado Pago

Testing Webhooks

Local Testing

Manual Testing