Webhooks

Webhooks avisam o seu sistema assim que algo acontece na ZynPay — sem precisar ficar consultando a API. São criados pelo painel, com a sua sessão logada (não com uma chave de API).

Criar um endpoint

Acesse Integrações → Webhooks

No painel, abra Integrações e clique em Novo webhook.

Informe a URL

Deve ser uma URL HTTPS pública (não são aceitos IPs privados/localhost).

Escolha os eventos

Selecione um ou mais dos eventos abaixo (até 10).

Guarde o secret

O secret (zwhsec_...) usado para validar a assinatura é exibido uma única vez, na criação.

Eventos disponíveis

Evento	Quando é disparado
`pix.charge.paid`	Uma cobrança Pix foi paga.
`withdrawal.paid`	Um saque foi liquidado (Pix enviado).
`withdrawal.rejected`	Um saque foi rejeitado e o valor voltou ao saldo disponível.
`infraction.updated`	Uma infração/disputa relacionada a uma cobrança foi atualizada.

Formato do payload

Toda entrega é um POST com corpo JSON neste formato:

{
  "id": "evt_9f2a...",
  "type": "pix.charge.paid",
  "createdAt": "2026-08-25T13:05:00.000Z",
  "data": {
    "merchantId": "a812...",
    "chargeId": "5c9a...",
    "amountCents": 5000,
    "feeCents": 199,
    "netAmountCents": 4801,
    "paidAt": "2026-08-25T13:05:00.000Z"
  }
}

Validando a assinatura

Cada requisição chega com dois cabeçalhos:

Cabeçalho	Conteúdo
`x-zinpay-event-id`	ID único do evento (use para evitar processar o mesmo evento duas vezes).
`x-zinpay-signature`	HMAC-SHA256, em hexadecimal, do corpo bruto da requisição usando o seu webhook secret.

Verifique a assinatura antes de confiar no payload:

import { createHmac, timingSafeEqual } from "node:crypto";

function isValidZynPaySignature(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Calcule o HMAC sobre o corpo bruto da requisição (antes de fazer JSON.parse). Reserializar o JSON pode mudar a ordem/espaçamento dos bytes e invalidar a comparação.

Responda rápido

Seu endpoint deve responder com um status 2xx em até poucos segundos. Se a entrega falhar (timeout, erro, redirecionamento), a ZynPay tenta novamente com backoff exponencial; depois de esgotar as tentativas, o evento fica marcado como dead_letter e você pode reenviá-lo manualmente pelo painel — veja Ciclo de vida de uma cobrança para reenviar a notificação de um pagamento específico.

Trate o mesmo x-zinpay-event-id como possivelmente repetido — sua rota deve ser idempotente.

Introdução

Cobranças

Saldo

Erros

Webhooks

Criar um endpoint

Eventos disponíveis

Formato do payload

Validando a assinatura

Responda rápido

​Criar um endpoint

​Eventos disponíveis

​Formato do payload

​Validando a assinatura

​Responda rápido

Criar um endpoint

Eventos disponíveis

Formato do payload

Validando a assinatura

Responda rápido