Webhooks

Um webhook avisa o seu sistema quando algo acontece na loja: um pedido pago, um reembolso, um acesso revogado, uma entrega que falhou. A MinePag envia um POST com o evento em JSON para a URL que você cadastrar, assinado no padrão Standard Webhooks.

A lista de eventos e os dados de cada um estão em Eventos de webhook.

Cadastrar um endpointCopiar link da seção

Só Proprietário e Administrador da loja gerenciam webhooks.

Gerenciar pela APICopiar link da seção

Os endpoints também podem ser gerenciados pela API, com uma chave secreta com os escopos webhooks:read e webhooks:write. Isso é útil para um app que se cadastra sozinho ao ser instalado na loja.

As alterações feitas pela API ficam nos logs de auditoria com a chave de API como autora. Veja os detalhes na referência da API.

O que a MinePag enviaCopiar link da seção

POST /webhooks/minepag HTTP/1.1
Content-Type: application/json
User-Agent: MinePag-Webhooks/1.0 (+https://minepag.com.br)
webhook-id: 0193b7c3-1001-7abc-8def-100000000001
webhook-timestamp: 1791815473
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"id":"0193b7c3-1001-7abc-8def-100000000001","type":"order.paid","apiVersion":"2026-10-01","createdAt":"2026-10-12T14:31:13.000Z","projectId":"…","data":{…}}

Resposta esperadaCopiar link da seção

• Responda 2xx em até 10 segundos. Qualquer outro status, falha de conexão ou demora conta como falha.
• Redirecionamentos (3xx) não são seguidos e contam como falha.
• O corpo da sua resposta é ignorado. O primeiro 1 KB fica no histórico do endpoint para ajudar a investigar falhas.

Verificar a assinaturaCopiar link da seção

Verifique toda requisição antes de confiar nela. A assinatura é um HMAC-SHA256 de {webhook-id}.{webhook-timestamp}.{corpo} com o segredo do endpoint (o trecho depois de whsec_, decodificado de base64), codificado em base64.

Os passos:

1. Leia webhook-id, webhook-timestamp e webhook-signature. Se faltar algum, recuse.
2. Recuse se o horário estiver a mais de 5 minutos do relógio do seu servidor. Isso impede que alguém reenvie uma requisição antiga capturada.
3. Calcule o HMAC esperado e compare, em tempo constante, com cada assinatura v1 do cabeçalho. Basta uma bater.
4. Só então leia o JSON e processe.

import { createHmac, timingSafeEqual } from 'node:crypto';
import express from 'express';

const TOLERANCE_SECONDS = 5 * 60;

export function verifyMinePagWebhook(rawBody, headers, secret) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures) return false;

  const now = Math.floor(Date.now() / 1000);
  if (!/^\d+$/.test(timestamp) || Math.abs(now - Number(timestamp)) > TOLERANCE_SECONDS) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(rawBody).digest();

  return signatures.split(' ').some(entry => {
    const [version, signature] = entry.split(',');
    if (version !== 'v1' || !signature) return false;
    const received = Buffer.from(signature, 'base64');
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

const app = express();

// express.raw mantém o corpo como Buffer, sem reserializar o JSON
app.post('/webhooks/minepag', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyMinePagWebhook(req.body, req.headers, process.env.MINEPAG_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const event = JSON.parse(req.body.toString('utf8'));
  res.status(200).end();
  queueEventProcessing(event);
});

queueEventProcessing representa a sua fila ou rotina de processamento. Se preferir, as bibliotecas oficiais do padrão Standard Webhooks, disponíveis para várias linguagens, também verificam os envios da MinePag com o mesmo segredo whsec_.

Novas tentativasCopiar link da seção

Quando o envio falha, a MinePag tenta de novo com estes intervalos:

São 7 tentativas no total; a última acontece cerca de 32 horas e meia depois da primeira. Todas usam o mesmo webhook-id. Se a 7ª também falhar, o envio fica como Tentativas esgotadas e só volta a ser enviado se alguém usar Reenviar evento no painel.

Situação do endpointCopiar link da seção

Para voltar a receber, corrija o destino e use Reativar endpoint (ou PATCH /webhook-endpoints/{endpointId} com enabled: true). Ao desativar, as tentativas que estavam agendadas ficam como Tentativas esgotadas; depois de reativar, você pode reenviá-las pelo histórico. Eventos que aconteceram enquanto o endpoint estava desativado não são enviados nem aparecem no histórico: busque esses dados pela API (veja Conciliação diária).

Histórico e reenvioCopiar link da seção

A página do endpoint lista cada tentativa com o evento, a situação (Pendente, Entregue, Nova tentativa agendada ou Tentativas esgotadas), o status HTTP e o tempo de resposta. Abra uma tentativa para ver os dados enviados e o trecho da resposta do seu servidor.

Use Reenviar evento para mandar o mesmo evento de novo, com o mesmo webhook-id. O reenvio manual é uma tentativa avulsa: se falhar, não agenda outras. O reenvio fica nos logs de auditoria.

Trocar o segredoCopiar link da seção

Troque o segredo se ele vazar ou periodicamente:

1. Na página do endpoint, clique em Gerar novo segredo e confirme. Pela API, use POST /webhook-endpoints/{endpointId}/rotate-secret.
2. Copie o segredo novo. Por 24 horas, cada envio leva duas assinaturas no webhook-signature: uma com o segredo novo e outra com o anterior.
3. Atualize o segredo no seu sistema dentro desse prazo. Os exemplos acima já aceitam qualquer uma das assinaturas, então a troca não perde eventos.
4. Depois de 24 horas, só o segredo novo assina.

Boas práticasCopiar link da seção

• Responda rápido e processe depois. Valide a assinatura, coloque o evento numa fila e responda 2xx. Processamentos longos estouram os 10 segundos e geram reenvios.
• Deduplique pelo webhook-id. O mesmo evento pode chegar mais de uma vez (nova tentativa, reenvio manual, sua resposta perdida no caminho). Guarde os ids processados e ignore repetidos.
• Não dependa da ordem. Eventos podem chegar fora de ordem. Use createdAt do envelope ou consulte o recurso pela API antes de sobrescrever um estado.
• Ignore tipos que você não conhece. Responda 2xx e siga em frente: novos eventos podem surgir.
• Confirme o que é crítico. Antes de liberar algo de alto valor, você pode consultar o pedido com GET /orders/{orderId}.
• Um endpoint por finalidade. Separe o que é ERP, o que é suporte e o que é serviço de entrega: cada um com seu segredo e seus eventos.
• Proteja o segredo. Guarde em variável de ambiente ou cofre de segredos, nunca no código.

Problemas comunsCopiar link da seção