Webhooks (também conhecido como retorno de chamada web) são um método simples que permite a uma aplicação ou sistema fornecer informações em tempo real sempre que um evento ocorre. É uma forma passiva de receber dados entre dois sistemas por meio de uma solicitação HTTP POST.

As notificações Webhooks podem ser configuradas para cada uma das aplicações criadas em Suas integrações. Você também poderá configurar uma URL de teste que, junto com suas credenciais de teste, permitirá testar o funcionamento correto das suas notificações antes de sair à produção.

Uma vez configuradas, as notificações Webhooks serão enviadas sempre que ocorrer um ou mais eventos cadastrados. Isso evita a necessidade de verificações constantes, prevenindo a sobrecarga do sistema e a perda de dados em situações críticas.

Para configurar as notificações Webhooks, escolha entre uma das opções abaixo:

Uma vez que as notificações estiverem configuradas, consulte as ações necessárias após receber uma notificação para validar se foram devidamente recebidas.

Configure notificações para cada aplicação diretamente em Suas integrações de forma eficiente e segura. Nesta documentação, explicaremos como:

1. Indicar URLs e configurar eventos
2. Validar origem da notificação
3. Simular o recebimento da notificação

Para configurar as notificações Webhooks via Suas integrações, é necessário indicar as URLs onde elas serão recebidas e especificar os eventos para os quais deseja receber notificações.

Para isso, siga as etapas descritas abaixo.

1. Acesse Suas integrações e selecione a aplicação para a qual deseja ativar as notificações. Caso ainda não tenha criado uma aplicação, acesse a documentação Painel do Desenvolvedor e siga as instruções.
2. No menu à esquerda, vá até Webhooks > Configurar notificações e configure as URLs que serão usadas para receber as notificações. Recomendamos utilizar uma URL diferente para o modo de teste e o modo produção:
   • URL modo teste: fornece uma URL que permite testar o correto funcionamento das notificações dessa aplicação durante a fase de teste ou desenvolvimento. O teste dessas notificações deverá ser realizado exclusivamente com as credenciais de teste de usuários produtivos.
   • URL modo produção: fornece uma URL para receber notificações com sua integração produtiva. Essas notificações deverão ser configuradas com credenciais produtivas.

3. Selecione os eventos para os quais deseja receber notificações em formato json através de um HTTP POST para a URL especificada anteriormente. Um evento pode ser qualquer atualização no objeto relatado, incluindo alterações de status ou atributos. Consulte a tabela abaixo para ver os eventos configuráveis, considerando a solução do Mercado Pago integrada e suas necessidades de negócio.

4. Por fim, clique e Salvar para gerar uma assinatura secreta exclusiva para a sua aplicação, permitindo validar a autenticidade das notificações recebidas e garantir que tenham sido enviadas pelo Mercado Pago. A assinatura gerada não tem prazo de validade e sua renovação periódica não é obrigatória, embora seja altamente recomendável. Para renová-la, clique no botão de redefinição ao lado da assinatura.

As notificações enviadas pelo Mercado Pago serão semelhantes ao exemplo abaixo para um alerta do tópico payment:

json
Copiar
{
 "id": 12345,
 "live_mode": true,
 "type": "payment",
 "date_created": "2015-03-25T10:04:58.396-04:00",
 "user_id": 44444,
 "api_version": "v1",
 "action": "payment.created",
 "data": {
     "id": "999999999"
 }
}

O Mercado Pago sempre incluirá a assinatura secreta nas notificações Webhooks recebidas na URL cadastrada. Isso permitirá validar a sua autenticidade, proporcionando maior segurança e prevenindo possíveis fraudes.

Esta assinatura será enviada no header x-signature, conforme o exemplo abaixo.

x-signature
Copiar
`ts=1704908010,v1=618c85345248dd820d5fd456117c2ab2ef8eda45a0282ff693eac24131a5e839`

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

Ao receber uma notificação em sua plataforma, o Mercado Pago aguarda uma resposta para validar se você a recebeu corretamente. Para isso, é necessário retornar um status HTTP STATUS 200 (OK) ou 201 (CREATED).

O tempo de espera para a confirmação da recepção das notificações 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á novas tentativas de envio a cada 15 minutos, até receber uma resposta. Após a terceira tentativa, o prazo será prorrogado, mas os envios continuarão acontecendo.

Após responder à notificação e confirmar seu recebimento, é possível obter as informações completas do recurso notificado fazendo uma requisição ao endpoint correspondente da API. Para identificar qual endpoint utilizar, confira a tabela abaixo:

Com essas informações, você poderá realizar as atualizações necessárias na sua plataforma como, por exemplo, atualizar um pagamento aprovado.

O painel de notificações permite ao usuário visualizar os eventos disparados sobre uma determinada integração, verificar o status e obter informações detalhadas desses eventos.

Este painel será exibido assim que você configurar suas notificações Webhooks, e você pode acessá-lo a qualquer momento clicando em Webhooks dentro de Suas integrações.

Entre as informações disponíveis estão a porcentagem de notificações entregues, bem como uma visão rápida das URLs e dos eventos configurados.

Além disso, você encontrará uma lista completa das últimas notificações enviadas e seus detalhes, como status da entrega (sucesso ou falha), ação (ação associada ao evento disparado), evento (tipo de evento disparado) e data e hora. Se desejar, é possível filtrar esses resultados exibidos por status da entrega e por período (data e hora).

Ao clicar em uma das notificações listadas, é possível acessar os detalhes do evento. Esta seção fornece mais informações e permite a recuperação de dados perdidos em caso de falha na entrega da notificação para manter o sistema sempre atualizado.

• Status: Status do evento junto com o código de sucesso ou erro correspondente.
• Evento: Tipo de evento disparado, conforme selecionado na configuração das notificações.
• Tipo: Tópico ao qual o evento disparado pertence, conforme a seleção feita durante a configuração.
• Data e hora do disparo: Data e hora em que o evento foi disparado.
• Descrição: Descrição detalhada do evento conforme documentada.
• ID do disparo: Identificador único da notificação enviada.
• Requisição: JSON da requisição correspondente à notificação disparada.

Em caso de falha na entrega da notificação, é possível visualizar os motivos e corrigir as informações necessárias para evitar problemas futuros.