Configurar notificações

A seguir, apresentaremos um passo a passo para poder receber notificações de pagamento em integrações com Point. Uma vez configuradas, as notificações Webhook serão enviadas sempre que ocorrer qualquer atualização sobre o tópico reportado, incluindo criação e atualização de orders e processamento de transações.

1. Acesse Suas integrações e selecione a aplicação integrada com Point para a qual deseja ativar as notificações.

2. No menu à esquerda, selecione Webhooks > Configurar notificações.

3. Selecione a aba Modo de produção e forneça uma URL HTTPS para receber notificações com sua integração produtiva.

4. Selecione o evento Order (Mercado Pago) para receber notificações, que serão enviadas em formato JSON através de um HTTPS POST para a URL especificada anteriormente.

5. Por fim, clique em Salvar configuração. Uma chave secreta exclusiva será gerada para a aplicação, o que permitirá validar a autenticidade das notificações recebidas e garantir que sejam enviadas pelo Mercado Pago. Tenha em mente que esta chave não tem prazo de validade e sua renovação periódica não é obrigatória, embora seja recomendada. Para isso, basta clicar no botão Redefinir.

Ao concluir, suas notificações Webhooks para o Mercado Pago Point estarão configuradas e você poderá receber os seguintes alertas sobre a order:

• Processada (order.processed)
• Cancelada (order.canceled)
• Reembolsada (order.refunded)
• Exige confirmação no terminal (order.action_required)
• Falhou (order.failed)
• Expirada (order.expired)

Para garantir que as notificações sejam configuradas corretamente, é necessário simular sua recepção. Para isso, siga o passo a passo abaixo.

1. Após configurar seus Webhooks, clique em Simular notificação.
2. Na tela de simulação, selecione a URL que será testada.
3. Em seguida, selecione o tipo de evento e insira a identificação que será enviada no corpo da notificação (Data ID).

4. Por fim, clique em Enviar teste para verificar a solicitação, a resposta fornecida pelo servidor e a descrição do evento. Você receberá uma resposta conforme os exemplos abaixo, que representam o body da notificação recebida em seu servidor.

json
{
  "action": "order.processed",
  "api_version": "v1",
  "application_id": "123456",
  "data": {
    "external_reference": "ext_ref_1235",
    "id": "ORD01JYH1Z1YJN4HZ8J3Q0RB3YP6D",
    "status": "processed",
    "status_detail": "accredited",
    "total_paid_amount": "120",
    "transactions": {
      "payments": [
        {
          "amount": "120",
          "id": "PAY01K22Y503EJ8JHGF64KGY1PZ2B",
          "paid_amount": "120",
          "payment_method": {
            "id": "debvisa",
            "installments": 1,
            "type": "debit_card"
          },
          "reference": {
            "id": "123456789980"
          },
          "status": "processed",
          "status_detail": "accredited"
        }
      ]
    },
    "type": "point",
    "version": 3
  },
  "date_created": "2025-08-07T18:54:40.851374414Z",
  "live_mode": true,
  "type": "order",
  "user_id": "123456"
}

A validação da origem de uma notificação é fundamental para garantir a segurança e a autenticidade das informações recebidas. Este processo ajuda a prevenir fraudes e garante que somente as notificações legítimas sejam processadas.

O Mercado Pago enviará ao seu servidor uma notificação similar ao exemplo abaixo para um alerta do tema order. Neste exemplo, está incluída a notificação completa, que contém os query params, o body e o header da notificação.

• Query params: São parâmetros de consulta que acompanham a URL. No exemplo, temos data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3 e type=order.
• Body: O corpo da notificação contém informações detalhadas sobre o evento, como action, api_version, application_id, date_created, id, live_mode, type, user_id e data.
• Header: O cabeçalho contém metadados importantes, incluindo a assinatura secreta da notificação x-signature.

plain
POST /test?data.id=ORD01JQ4S4KY8HWQ6NA5PXB65B3D3&type=order HTTP/1.1
Host: prueba.requestcatcher.com
Accept: */*
Accept-Encoding: *
Connection: keep-alive
Content-Length: 177
Content-Type: application/json
Newrelic: eyJ2IjpbMCwxXSwiZCI6eyJ0eSI6IkFwcCIsImFjIjoiOTg5NTg2IiwiYXAiOiI5NjA2MzYwOTQiLCJ0eCI6ImY4MzljZjg4ODg2MGRmZTIiLCJ0ciI6ImMwOGMwZGMyMjNjZDY2YjJkZWQwMjUxZmYxNWNiNGQ1IiwicHIiOjEuMjUwMzIsInNhIjp0cnVlLCJ0aSI6MTc0Mjg0MjU4MDE2NCwiaWQiOiIxOGI2NDcxNjNkNzI3NjU4IiwidGsiOiIxNzA5NzA3In19=
Traceparent: 00-c08c0dc223cd66b2ded0251ff15cb4d5-18b647163d727658-01
Tracestate: 1709707@nr=0-0-989586-960636094-18b647163d727658-f839cf888860dfe2-1-1.250320-1742842580164
User-Agent: restclient-node/4.15.3
X-Request-Id: 2066ca19-c6f1-498a-be75-1923005edd06
X-Rest-Pool-Name: /services/webhooks.js
X-Retry: 0
X-Signature: ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b
X-Socket-Timeout: 22000
{"action":"order.action_required","api_version":"v1","application_id":"76506430185983","date_created":"2021-11-01T02:02:02Z","id":"123456","live_mode":false,"type":"order","user_id":2025701502,"data":{"id":"ORD01JQ4S4KY8HWQ6NA5PXB65B3D3"}}

A partir da notificação Webhook recebida, você poderá validar a autenticidade da sua origem. O Mercado Pago sempre incluirá a chave secreta nas notificações Webhooks que serão recebidas, o que permitirá validar sua autenticidade. Esta chave será enviada no header x-signature, que será similar ao exemplo abaixo.

plain
ts=1742505638683,v1=ced36ab6d33566bb1e16c125819b8d840d6b8ef136b0b9127c76064466f5229b

Para confirmar a validação, é necessário extrair a chave contida no header e compará-la com a chave fornecida para a sua aplicação em Suas integrações.

Siga uma das abordagens abaixo para validar a autenticidade da notificação.

<?php
use MercadoPago\Webhook\WebhookSignatureValidator;
use MercadoPago\Exceptions\InvalidWebhookSignatureException;

try {
    WebhookSignatureValidator::validate(
        $_SERVER['HTTP_X_SIGNATURE'],
        $_SERVER['HTTP_X_REQUEST_ID'],
        $_GET['data_id'],
        $secret
    );
    http_response_code(200);
} catch (InvalidWebhookSignatureException $e) {
    http_response_code(401);
}

import { WebhookSignatureValidator, InvalidWebhookSignatureError } from 'mercadopago';

try {
    WebhookSignatureValidator.validate({
        xSignature: req.headers['x-signature'],
        xRequestId: req.headers['x-request-id'],
        dataId:     req.query['data.id'],
        secret,
    });
    res.sendStatus(200);
} catch (err) {
    if (err instanceof InvalidWebhookSignatureError) res.status(401).end();
    else throw err;
}

from mercadopago.webhook import WebhookSignatureValidator, InvalidWebhookSignatureError

try:
    WebhookSignatureValidator.validate(
        request.headers.get("x-signature"),
        request.headers.get("x-request-id"),
        request.args.get("data.id"),
        secret,
    )
    return "", 200
except InvalidWebhookSignatureError:
    return "", 401

import "github.com/mercadopago/sdk-go/pkg/webhook"

err := webhook.ValidateSignature(
    r.Header.Get("x-signature"),
    r.Header.Get("x-request-id"),
    r.URL.Query().Get("data.id"),
    secret,
)
if err != nil {
    w.WriteHeader(http.StatusUnauthorized)
    return
}
w.WriteHeader(http.StatusOK)

using MercadoPago.Error;
using MercadoPago.Webhook;

try {
    WebhookSignatureValidator.Validate(
        xSignature: Request.Headers["x-signature"],
        xRequestId: Request.Headers["x-request-id"],
        dataId:     Request.Query["data.id"],
        secret:     secret);
    return Ok();
} catch (InvalidWebhookSignatureException) {
    return Unauthorized();
}

import com.mercadopago.webhook.WebhookSignatureValidator;
import com.mercadopago.exceptions.MPInvalidWebhookSignatureException;

try {
    WebhookSignatureValidator.validate(
        request.getHeader("x-signature"),
        request.getHeader("x-request-id"),
        request.getParameter("data.id"),
        secret);
    response.setStatus(200);
} catch (MPInvalidWebhookSignatureException e) {
    response.setStatus(401);
}

require 'mercadopago/webhook/validator'

begin
    Mercadopago::Webhook::Validator.validate(
        request.headers['x-signature'],
        request.headers['x-request-id'],
        request.params['data.id'],
        secret
    )
    head :ok
rescue Mercadopago::Webhook::InvalidWebhookSignatureError
    head :unauthorized
end

Quando você recebe uma notificação em sua plataforma, o Mercado Pago espera uma resposta para validar que essa recepção foi correta. Para isso, você deve devolver um HTTP STATUS 200 (OK) ou 201 (CREATED).

O tempo de espera para essa confirmação será de 22 segundos. Se essa confirmação não for enviada, o sistema entenderá que a notificação não foi recebida e realizará uma nova tentativa de envio a cada 15 minutos, até que receba a resposta. Após a terceira tentativa, o prazo será prorrogado, mas os envios continuarão acontecendo.

Após responder à notificação Webhook e confirmar seu recebimento, somente se as informações recebidas não forem suficientes e você necessite de informações adicionais, é possível obter todos os dados sobre o recurso notificado enviando uma solicitação ao endpoint /v1/orders/{id}GET.

Com essa informação, você poderá realizar as atualizações necessárias em sua plataforma, como atualizar um pagamento aprovado.