> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mingopay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba eventos assinados, deduplique entregas e trate novas tentativas.

No Node.js, o [SDK oficial](https://docs.mingopay.com.br/documentation/sdk.md) oferece `constructWebhookEvent(rawBody, signature, secret)` para validar a assinatura, o tempo e o envelope. Use os bytes originais recebidos e deduplique pelo identificador do evento no seu banco. O segredo é o do seu endpoint MingoPay.

Cadastre uma URL HTTPS pública na área **Webhooks** do dashboard. Para integrações de sistemas, o segredo `whsec_` aparece somente na criação.

## Notificações no Discord

Em **Novo endpoint**, escolha **Discord** e cole a URL copiada em **Configurações do canal > Integrações > Webhooks** no Discord. Selecione o ambiente e salve. A URL oficial também é reconhecida automaticamente. Use **Testar** e confira o canal e o histórico de entregas. O aviso de fila é informativo: a confirmação de entrega aparece somente após resposta 2xx do destino; falhas mostram um aviso de erro. O resultado e a lista de entregas são atualizados em tempo real, sem recarregar a página. Um canal de texto comum é suficiente; URLs com parâmetros de threads não são aceitas.

O painel inscreve pagamentos confirmados, devoluções, transferências concluídas ou com falha e atualizações de disputas. A mensagem exibe ID da transação MingoPay, status do evento, valor, taxa real registrada, data/hora de Brasília, ambiente e ID do evento. A taxa de devoluções/disputas se refere à transação original. Um teste se identifica como teste e não inventa valores ou status bancário. CPF, e-mail, chave Pix e payload completo não são enviados. Menções estão desativadas.

A URL contém o token de acesso ao canal: mantenha-a privada. Ela é criptografada ao cadastrar e aparece mascarada na listagem. Não é necessário copiar um segredo `whsec_` para usar o Discord. As mensagens usam o formato do Discord; o envelope e a assinatura descritos abaixo são exclusivos de endpoints de sistemas. Ambos os destinos mantêm histórico e retentativas. Uma resposta 429 do Discord aumenta a espera quando necessário, até uma hora. Entregas com resposta incerta podem produzir mensagem duplicada; confira o identificador na mensagem.

Essa configuração usa a sessão do painel e suas permissões. Não adiciona rotas Bearer ou métodos ao SDK.

## Formato da entrega

```http theme={"system"}
POST /seu-endpoint HTTP/1.1
Content-Type: application/json
X-MingoPay-Event: payment_intent.paid
X-MingoPay-Signature: t=1700000000,v1=<hex-hmac-sha256>
```

```json theme={"system"}
{
  "id": "<event-id>",
  "type": "payment_intent.paid",
  "createdAt": "<iso-date>",
  "data": {
    "paymentIntentId": "<payment-id>",
    "amountCents": 14990,
    "currency": "BRL"
  }
}
```

## Histórico e detalhes

Em **Entregas recentes > Detalhes**, consulte status HTTP, tentativa, referência da operação, URL de destino, horários e resposta. Novas tentativas registram o corpo exato enviado, armazenado com criptografia. O histórico anterior mostra **Dados do evento**, com um aviso de que o corpo original não foi registrado.

**Reenviar falha** mantém o mesmo identificador do evento e a numeração das tentativas. Abre até dez novas tentativas sem repetir endpoints já entregues. A ação exige endpoint ativo e evento falho ou esgotado; eventos na fila, em processamento ou já concluídos não são reenfileirados. Reenviar uma notificação não cria outra transação financeira.

## Validar a assinatura

Leia o corpo bruto e calcule HMAC-SHA256 sobre `timestamp + "." + rawBody`.

```javascript theme={"system"}
import { createHmac, timingSafeEqual } from "node:crypto";

export function validSignature(rawBody, header, secret) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? "");
  if (!match || Math.abs(Date.now() / 1000 - Number(match[1])) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${match[1]}.${rawBody}`)
    .digest();

  return timingSafeEqual(expected, Buffer.from(match[2], "hex"));
}
```

> [!WARNING]
>
> Não faça parse e stringify do JSON antes de validar. A assinatura usa os bytes exatos recebidos.

## Entrega segura

Persista o `id` do evento com restrição única, processe cada evento uma vez e responda `2xx` somente depois de aceitá-lo. Falhas e timeouts geram novas tentativas com intervalo crescente, até 10 tentativas.

Eventos de cobrança incluem `payment_intent.pending`, `payment_intent.paid`, `payment_intent.failed`, `payment_intent.cancelled` e `payment_intent.refunded`. O evento `ping.test` verifica o endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.