Webhooks

Sua aplicação não precisa consultar GET /payment-pix/get/:id em loop. Quando um pagamento confirma, a GoatPay envia um POST HTTPS para a URL cadastrada.

Sem porta pública HTTPS? Use WebSocket — conexão persistente com gp_live_... e subscribe por pattern (payment.*).

Configurar

1. Endpoint HTTPS

Exponha uma rota pública, por exemplo https://api.suaempresa.com/goatpay/webhook.

2. Cadastrar URL

Via API: POST /webhooks/create com sua chave gp_live_....

3. Guardar o segredo

Anote o whsec_... exibido uma única vez na criação.

4. Validar assinatura

Confira Segurança e assinatura em cada POST recebido.

Escopo por API key

Endpoints criados com POST /v1/webhooks/create ficam vinculados à chave usada. Recebem eventos das transações criadas pela mesma API key. Endpoints do dashboard (sem vínculo de chave) recebem eventos de toda a conta.

Teste

Dispare o evento webhook.test cadastrando o tipo na lista de events e processando um teste a partir do painel da conta, ou aguarde uma transação real da mesma API key.

Formato da entrega

Cada entrega é um POST com corpo JSON no formato abaixo. O campo event repete o tipo inscrito no endpoint; data carrega o payload do evento.

{
  "id": "clxxx_delivery",
  "event": "nome.do.evento",
  "createdAt": "2026-05-24T12:00:00.000Z",
  "data": {}
}

Campo	Descrição
`id`	ID único da entrega — use para idempotência (não confundir com `data.id` da transação).
`event`	Tipo do evento (igual a `x-goatpay-event`).
`createdAt`	Momento em que a entrega foi criada (ISO 8601).
`data`	Payload do evento — formato varia por tipo (veja Eventos).

O objeto data segue o mesmo formato enxuto das respostas /v1: sem provider, accountId, metadata, direction nem updatedAt. IDs do processador aparecem como referenceId; infrações MED como infractionId.

Tipos de `data`

Família	Eventos	Formato de referência
PIX recebido	`payment.`, `refund.`	GET /payment-pix/get, GET /refunds/get
PIX enviado	`transfer.` (exceto `transfer.internal.`)	GET /transfer-pix/get
Transferência interna	`transfer.internal.*`	GET /transfer-internal/get
MED	`med.*`	GET /meds/get
Link de pagamento	`payment_link.paid`	Objeto de sessão (abaixo)
Nota fiscal	`invoice.*`	Apenas `invoiceId` — consulte o painel ou a API fiscal da conta
OAuth 2.0	`oauth.*`	Objetos de autorização, aplicação e client (abaixo)
Teste	`webhook.test`	Metadados do disparo manual

Campos úteis em transações PIX

Campo	Quando aparece
`payer`	`payment.paid` de `PIX_IN` — nome e documento do pagador (omitido se não identificado).
`recipient`	`transfer.completed` de `PIX_OUT` — favorecido confirmado na liquidação.
`copyPaste`, `qrcodeUrl`, `qrCodeBase64`	Não vêm em webhooks nem WebSocket. Para exibir o QR, use a resposta de POST /payment-pix/create (`qrCodeBase64` incluso). Reconsulta pendente via GET /payment-pix/get retorna `copyPaste` e `qrcodeUrl` (sem `qrCodeBase64` desde 15/08/2026).
`expiresAt`	Cobrança PIX pendente ou expirada.
`securityReview`	`transfer.created` — saque retido para análise antifraude (`pending: true`).
`refund`	Eventos `refund.*` e `payment.refunded` — estado do estorno no depósito original.
`transferKind`, `recipientEmail`, `pairId`	Transferência interna (`INTERNAL_TRANSFER_*`).

Headers:

Content-Type: application/json
x-goatpay-event: payment.paid
x-goatpay-signature: sha256=<hmac do corpo JSON>
x-goatpay-delivery: <id da entrega>

A assinatura é calculada sobre o raw body (bytes exatos recebidos), não sobre um objeto re-serializado.

Segurança e assinatura

Cada entrega usa HMAC-SHA256 com o segredo whsec_... da criação do endpoint.

Validação (Node.js)

import crypto from "node:crypto";

export function verifyGoatPayWebhook(
  rawBody: string | Buffer,
  signatureHeader: string | undefined,
  webhookSecret: string,
): boolean {
  if (!signatureHeader?.startsWith("sha256=")) return false;
  const received = signatureHeader.slice("sha256=".length);
  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(typeof rawBody === "string" ? rawBody : Buffer.from(rawBody))
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Use timingSafeEqual na comparação. Nunca processe o evento sem validar x-goatpay-signature.

Retentativas

Se o endpoint não responder 2xx a tempo, a GoatPay reenvia com backoff: 1 min, 5 min, 15 min, 1 h, 4 h (até 5 tentativas).

Idempotência

Persista o id da entrega antes de processar. Duplicatas devem responder 200 sem efeito colateral.

const deliveryId = req.body.id;
if (await alreadyProcessed(deliveryId)) {
  return res.status(200).json({ ok: true });
}
await processEvent(req.body);
await markProcessed(deliveryId);
return res.status(200).json({ ok: true });

Checklist

URL HTTPS em produção
Validar x-goatpay-signature com o whsec_... correto
Responder 200 após processar ou enfileirar com segurança
Tratar o mesmo id de entrega apenas uma vez
Ignorar campos extras desconhecidos em data

Eventos

Inscreva os tipos abaixo em events ao criar o endpoint. Use "*" apenas se realmente precisar de todos os eventos futuros.

Catálogo (ativos)

Evento	Família
`payment.created`	PIX recebido
`payment.paid`	PIX recebido
`payment.failed`	PIX recebido
`payment.pix.expired`	PIX recebido
`payment.refunded`	PIX recebido (legado)
`refund.requested`	Estorno PIX
`refund.completed`	Estorno PIX
`refund.failed`	Estorno PIX
`transfer.created`	PIX enviado
`transfer.completed`	PIX enviado
`transfer.failed`	PIX enviado
`transfer.internal.completed`	Transferência interna
`transfer.internal.received`	Transferência interna
`med.created`	MED
`med.evidence_sent`	MED
`med.updated`	MED
`payment_link.paid`	Link de pagamento
`invoice.created`	Nota fiscal
`invoice.processing`	Nota fiscal
`invoice.issued`	Nota fiscal
`invoice.failed`	Nota fiscal
`invoice.cancelled`	Nota fiscal
`oauth.authorization.granted`	OAuth 2.0
`oauth.authorization.denied`	OAuth 2.0
`oauth.authorization.revoked`	OAuth 2.0
`oauth.application.created`	OAuth 2.0
`oauth.application.updated`	OAuth 2.0
`oauth.application.deleted`	OAuth 2.0
`oauth.client.created`	OAuth 2.0
`oauth.client.secret_regenerated`	OAuth 2.0
`oauth.client.redirect_uris_updated`	OAuth 2.0
`webhook.test`	Teste

Eventos de cripto e boleto existem no código mas não estão ativos na API pública no momento.

PIX recebido

Disparados por cobranças POST /payment-pix/create. Em todos os exemplos, data.type é PIX_IN.

Evento	Quando ocorre	`data.status`
`payment.created`	Cobrança registrada (aguardando pagamento).	`PENDING`
`payment.paid`	Depósito confirmado no SPI.	`COMPLETED`
`payment.failed`	Falha no fluxo de recebimento.	`FAILED`
`payment.pix.expired`	QR expirou sem pagamento.	`CANCELED`
`payment.refunded`	Estorno concluído (legado; mesmo payload de `refund.completed`).	`REVERSED`

payment.created — notificação de cobrança criada (payer omitido enquanto pendente; sem QR — guarde a resposta do POST /create):

{
  "id": "clxxx_delivery",
  "event": "payment.created",
  "createdAt": "2026-05-24T11:55:00.000Z",
  "data": {
    "id": "clx_transacao",
    "type": "PIX_IN",
    "status": "PENDING",
    "amount": 100,
    "feeAmount": 0.5,
    "netAmount": 99.5,
    "currency": "BRL",
    "externalReference": "pedido-123",
    "referenceId": "ref_pix_abc",
    "expiresAt": "2026-05-25T11:55:00.000Z",
    "createdAt": "2026-05-24T11:55:00.000Z"
  }
}

O QR (copyPaste, qrCodeBase64, qrcodeUrl) é retornado apenas na resposta de POST /payment-pix/create. O webhook payment.created não inclui esses campos — persista a resposta do create ao gerar a cobrança. Desde 15/08/2026, GET /payment-pix/get pendente retorna copyPaste e qrcodeUrl, mas não qrCodeBase64.

payment.paid — pagador identificado em payer:

{
  "id": "clxxx_delivery",
  "event": "payment.paid",
  "createdAt": "2026-05-24T12:00:00.000Z",
  "data": {
    "id": "clx_transacao",
    "type": "PIX_IN",
    "status": "COMPLETED",
    "amount": 100,
    "feeAmount": 0.5,
    "netAmount": 99.5,
    "currency": "BRL",
    "externalReference": "pedido-123",
    "referenceId": "ref_pix_abc",
    "endToEndId": "E12345678202505301234567890123456",
    "payer": {
      "name": "João da Silva",
      "document": "12345678909"
    },
    "completedAt": "2026-05-24T12:00:00.000Z",
    "createdAt": "2026-05-24T11:55:00.000Z"
  }
}

payment.failed:

{
  "id": "clxxx_delivery",
  "event": "payment.failed",
  "createdAt": "2026-05-24T13:00:00.000Z",
  "data": {
    "id": "clx_transacao",
    "type": "PIX_IN",
    "status": "FAILED",
    "amount": 100,
    "feeAmount": 0.5,
    "netAmount": 99.5,
    "currency": "BRL",
    "externalReference": "pedido-123",
    "referenceId": "ref_pix_abc",
    "createdAt": "2026-05-24T11:55:00.000Z"
  }
}

payment.pix.expired:

{
  "id": "clxxx_delivery",
  "event": "payment.pix.expired",
  "createdAt": "2026-05-25T11:55:00.000Z",
  "data": {
    "id": "clx_transacao",
    "type": "PIX_IN",
    "status": "CANCELED",
    "amount": 100,
    "feeAmount": 0.5,
    "netAmount": 99.5,
    "currency": "BRL",
    "externalReference": "pedido-123",
    "referenceId": "ref_pix_abc",
    "expiresAt": "2026-05-25T11:55:00.000Z",
    "createdAt": "2026-05-24T11:55:00.000Z"
  }
}

payment.refunded — disparado junto com refund.completed; prefira refund.completed em integrações novas:

{
  "id": "clxxx_delivery",
  "event": "payment.refunded",
  "createdAt": "2026-05-30T16:00:00.000Z",
  "data": {
    "id": "clx_pix_in",
    "type": "PIX_IN",
    "status": "REVERSED",
    "amount": 100,
    "feeAmount": 0.5,
    "netAmount": 99.5,
    "currency": "BRL",
    "externalReference": "pedido-123",
    "referenceId": "ref_pix_abc",
    "endToEndId": "E12345678202505301234567890123456",
    "completedAt": "2026-05-24T12:00:00.000Z",
    "createdAt": "2026-05-24T11:55:00.000Z",
    "refund": {
      "status": "COMPLETED",
      "refundId": "devolucao-pedido-123",
      "requestedAt": "2026-05-30T15:58:00.000Z",
      "completedAt": "2026-05-30T16:00:00.000Z",
      "debitNet": 99.5,
      "depositNet": 99.5,
      "transferFee": 0,
      "nature": "ORIGINAL",
      "description": "Estorno pedido #123"
    }
  }
}

Estorno PIX (depósito recebido)

Disparados após POST /refunds/create. O data é o depósito original com bloco refund.

Evento	Quando ocorre
`refund.requested`	Estorno aceito; saldo reservado; aguardando SPI.
`refund.completed`	Devolução confirmada — também dispara `payment.refunded`.
`refund.failed`	Estorno não concluído; saldo restaurado.

refund.requested:

{
  "id": "clxxx_delivery",
  "event": "refund.requested",
  "createdAt": "2026-05-30T15:58:00.000Z",
  "data": {
    "id": "clx_pix_in",
    "type": "PIX_IN",
    "status": "PROCESSING",
    "amount": 100,
    "feeAmount": 0.5,
    "netAmount": 99.5,
    "currency": "BRL",
    "externalReference": "pedido-123",
    "referenceId": "ref_pix_abc",
    "endToEndId": "E12345678202505301234567890123456",
    "completedAt": "2026-05-24T12:00:00.000Z",
    "createdAt": "2026-05-24T11:55:00.000Z",
    "refund": {
      "status": "PROCESSING",
      "refundId": "devolucao-pedido-123",
      "requestedAt": "2026-05-30T15:58:00.000Z",
      "completedAt": null,
      "debitNet": 99.5,
      "depositNet": 99.5,
      "transferFee": 0,
      "nature": "ORIGINAL",
      "description": "Estorno pedido #123"
    }
  }
}

refund.completed:

{
  "id": "clxxx_delivery",
  "event": "refund.completed",
  "createdAt": "2026-05-30T16:00:00.000Z",
  "data": {
    "id": "clx_pix_in",
    "type": "PIX_IN",
    "status": "REVERSED",
    "amount": 100,
    "feeAmount": 0.5,
    "netAmount": 99.5,
    "currency": "BRL",
    "externalReference": "pedido-123",
    "referenceId": "ref_pix_abc",
    "endToEndId": "E12345678202505301234567890123456",
    "completedAt": "2026-05-24T12:00:00.000Z",
    "createdAt": "2026-05-24T11:55:00.000Z",
    "refund": {
      "status": "COMPLETED",
      "refundId": "devolucao-pedido-123",
      "requestedAt": "2026-05-30T15:58:00.000Z",
      "completedAt": "2026-05-30T16:00:00.000Z",
      "debitNet": 99.5,
      "depositNet": 99.5,
      "transferFee": 0,
      "nature": "ORIGINAL",
      "description": "Estorno pedido #123"
    }
  }
}

refund.failed:

{
  "id": "clxxx_delivery",
  "event": "refund.failed",
  "createdAt": "2026-05-30T15:59:00.000Z",
  "data": {
    "id": "clx_pix_in",
    "type": "PIX_IN",
    "status": "COMPLETED",
    "amount": 100,
    "feeAmount": 0.5,
    "netAmount": 99.5,
    "currency": "BRL",
    "externalReference": "pedido-123",
    "referenceId": "ref_pix_abc",
    "endToEndId": "E12345678202505301234567890123456",
    "completedAt": "2026-05-24T12:00:00.000Z",
    "createdAt": "2026-05-24T11:55:00.000Z",
    "refund": {
      "status": "AVAILABLE",
      "refundId": "devolucao-pedido-123",
      "requestedAt": "2026-05-30T15:58:00.000Z",
      "completedAt": null,
      "debitNet": null,
      "depositNet": null,
      "transferFee": null,
      "nature": "ORIGINAL",
      "description": "Estorno pedido #123"
    }
  }
}

PIX enviado

Disparados por POST /transfer-pix/create. Em todos os exemplos, data.type é PIX_OUT.

Evento	Quando ocorre	`data.status`
`transfer.created`	Saída registrada (pendente ou em análise).	`PENDING` / `PROCESSING`
`transfer.completed`	PIX liquidado no favorecido.	`COMPLETED`
`transfer.failed`	Falha, cancelamento ou expiração.	`FAILED` / `CANCELED`

transfer.created — recipient omitido até liquidar; pode incluir securityReview:

{
  "id": "clxxx_delivery",
  "event": "transfer.created",
  "createdAt": "2026-06-01T13:00:00.000Z",
  "data": {
    "id": "clx_transacao",
    "type": "PIX_OUT",
    "status": "PROCESSING",
    "amount": 50,
    "feeAmount": 0.45,
    "netAmount": 52,
    "currency": "BRL",
    "externalReference": "saque-123",
    "referenceId": "ref_out_xyz",
    "pixKey": "12345678909",
    "pixKeyType": "CPF",
    "createdAt": "2026-06-01T13:00:00.000Z",
    "securityReview": {
      "pending": true,
      "maxHours": 24,
      "message": "Sua transferência será aprovada pela equipe. Se levar mais de 30 minutos, contate o suporte."
    }
  }
}

transfer.completed — recipient preenchido após liquidação:

{
  "id": "clxxx_delivery",
  "event": "transfer.completed",
  "createdAt": "2026-06-01T13:05:00.000Z",
  "data": {
    "id": "clx_transacao",
    "type": "PIX_OUT",
    "status": "COMPLETED",
    "amount": 50,
    "feeAmount": 0.45,
    "netAmount": 52,
    "currency": "BRL",
    "externalReference": "saque-123",
    "referenceId": "ref_out_xyz",
    "endToEndId": "E12345678202505301234567890123456",
    "pixKey": "12345678909",
    "pixKeyType": "CPF",
    "recipient": {
      "name": "Maria Recebedora",
      "document": "12345678909"
    },
    "completedAt": "2026-06-01T13:05:00.000Z",
    "createdAt": "2026-06-01T13:00:00.000Z"
  }
}

transfer.failed:

{
  "id": "clxxx_delivery",
  "event": "transfer.failed",
  "createdAt": "2026-06-01T13:10:00.000Z",
  "data": {
    "id": "clx_transacao",
    "type": "PIX_OUT",
    "status": "FAILED",
    "amount": 50,
    "feeAmount": 0.45,
    "netAmount": 52,
    "currency": "BRL",
    "externalReference": "saque-123",
    "referenceId": "ref_out_xyz",
    "pixKey": "12345678909",
    "pixKeyType": "CPF",
    "createdAt": "2026-06-01T13:00:00.000Z"
  }
}

Transferência interna

Disparados por POST /transfer-internal/create. Dois eventos por operação:

Evento	Conta	`data.type`
`transfer.internal.completed`	Origem	`INTERNAL_TRANSFER_OUT`
`transfer.internal.received`	Destino	`INTERNAL_TRANSFER_IN`

transfer.internal.completed:

{
  "id": "clxxx_delivery",
  "event": "transfer.internal.completed",
  "createdAt": "2026-06-03T10:00:00.000Z",
  "data": {
    "id": "clx_out",
    "type": "INTERNAL_TRANSFER_OUT",
    "status": "COMPLETED",
    "amount": 100,
    "feeAmount": 0,
    "netAmount": 100,
    "currency": "BRL",
    "externalReference": "repasse-parceiro",
    "transferKind": "internal",
    "recipientEmail": "destino@empresa.com",
    "recipientName": "Empresa Destino",
    "pairId": "pair_abc",
    "completedAt": "2026-06-03T10:00:00.000Z",
    "createdAt": "2026-06-03T10:00:00.000Z"
  }
}

transfer.internal.received:

{
  "id": "clxxx_delivery",
  "event": "transfer.internal.received",
  "createdAt": "2026-06-03T10:00:00.000Z",
  "data": {
    "id": "clx_in",
    "type": "INTERNAL_TRANSFER_IN",
    "status": "COMPLETED",
    "amount": 100,
    "feeAmount": 0,
    "netAmount": 100,
    "currency": "BRL",
    "transferKind": "internal",
    "counterpartyName": "Empresa Origem",
    "pairId": "pair_abc",
    "completedAt": "2026-06-03T10:00:00.000Z",
    "createdAt": "2026-06-03T10:00:00.000Z"
  }
}

transfer.internal.received vai para endpoints da conta destino, não da API key que originou o envio.

MED

Disputas MED no trilho PADRAO (PIX regulado). O objeto data segue o mesmo formato de GET /meds/get.

Evento	Quando ocorre
`med.created`	Nova disputa aberta; saldo bloqueado. Status `OPEN`.
`med.evidence_sent`	Defesa enviada via POST /meds/evidence; status passa para `UNDER_REVIEW`.
`med.updated`	Resultado final: `ACCEPTED`, `REJECTED`, `CANCELED` ou `EXPIRED`.

Exemplo med.created:

{
  "id": "clxxx_delivery",
  "event": "med.created",
  "createdAt": "2026-05-28T12:00:00.000Z",
  "data": {
    "id": "clx_med",
    "protocol": "MED-123",
    "transactionId": "clx_pix_in",
    "status": "OPEN",
    "amount": 99.9,
    "currency": "BRL",
    "reason": "Não reconhecimento da transação",
    "infractionId": "inf_abc",
    "endToEndId": "E12345678202505281234567890123456",
    "openedAt": "2026-05-28T12:00:00.000Z",
    "dueAt": "2026-06-04T12:00:00.000Z",
    "resolvedAt": null
  }
}

Exemplo med.evidence_sent:

{
  "id": "clxxx_delivery",
  "event": "med.evidence_sent",
  "createdAt": "2026-05-29T14:30:00.000Z",
  "data": {
    "id": "clx_med",
    "protocol": "MED-123",
    "transactionId": "clx_pix_in",
    "status": "UNDER_REVIEW",
    "amount": 99.9,
    "currency": "BRL",
    "reason": "Não reconhecimento da transação",
    "infractionId": "inf_abc",
    "endToEndId": "E12345678202505281234567890123456",
    "openedAt": "2026-05-28T12:00:00.000Z",
    "dueAt": "2026-06-04T12:00:00.000Z",
    "resolvedAt": null
  }
}

Exemplo med.updated (disputa rejeitada — saldo liberado):

{
  "id": "clxxx_delivery",
  "event": "med.updated",
  "createdAt": "2026-06-02T10:00:00.000Z",
  "data": {
    "id": "clx_med",
    "protocol": "MED-123",
    "transactionId": "clx_pix_in",
    "status": "REJECTED",
    "amount": 99.9,
    "currency": "BRL",
    "reason": "Não reconhecimento da transação",
    "infractionId": "inf_abc",
    "endToEndId": "E12345678202505281234567890123456",
    "openedAt": "2026-05-28T12:00:00.000Z",
    "dueAt": "2026-06-04T12:00:00.000Z",
    "resolvedAt": "2026-06-02T10:00:00.000Z"
  }
}

Links de pagamento

Evento	Quando ocorre
`payment_link.paid`	Checkout de link confirmado (PIX).

payment_link.paid — payload próprio (não é PIX_IN):

{
  "id": "clxxx_delivery",
  "event": "payment_link.paid",
  "createdAt": "2026-06-02T15:00:00.000Z",
  "data": {
    "sessionId": "clx_session",
    "status": "PAID",
    "method": "PIX",
    "amount": 99.9,
    "feeAmount": 5.15,
    "netAmount": 94.75,
    "currency": "BRL",
    "transactionId": "clx_tx",
    "externalReference": "pedido-42",
    "paidAt": "2026-06-02T15:00:00.000Z",
    "payer": {
      "name": "Maria",
      "document": "12345678909",
      "email": "maria@email.com",
      "phone": "11999999999"
    },
    "paymentLink": {
      "id": "clx_link",
      "name": "Plano Pro",
      "slug": "plano-pro",
      "publicCode": "abc12"
    }
  }
}

Para links pagos via PIX, payment.paid também pode ser emitido (formato de PIX recebido). Para checkout de link, inscreva-se em payment_link.paid.

Nota fiscal

Emitidos quando a cobrança usa emitFiscalInvoice: true e a emissão automática está ativa. O webhook traz apenas o ID.

Evento	Quando ocorre
`invoice.created`	Nota enfileirada após pagamento.
`invoice.processing`	Em processamento no emissor.
`invoice.issued`	Nota emitida.
`invoice.failed`	Falha ou rejeição.
`invoice.cancelled`	Nota cancelada.

{
  "id": "clxxx_delivery",
  "event": "invoice.issued",
  "createdAt": "2026-06-02T15:01:00.000Z",
  "data": {
    "invoiceId": "clx_invoice"
  }
}

OAuth 2.0

Eventos do ciclo de vida de aplicações OAuth e autorizações de terceiros. Não incluem emissão ou refresh de tokens (alto volume).

Evento	Quando ocorre	Quem recebe
`oauth.authorization.granted`	Usuário aprova o consentimento	Dono da aplicação e conta autorizada
`oauth.authorization.denied`	Usuário nega o consentimento	Dono da aplicação
`oauth.authorization.revoked`	Autorização revogada (usuário, dono do app, automático ou segurança)	Dono da aplicação e conta autorizada
`oauth.application.created`	Nova aplicação OAuth registrada	Dono da aplicação
`oauth.application.updated`	Metadados ou scopes da aplicação alterados	Dono da aplicação
`oauth.application.deleted`	Aplicação removida	Dono da aplicação
`oauth.client.created`	Credenciais DEV ou PRODUCTION geradas pela 1ª vez	Dono da aplicação
`oauth.client.secret_regenerated`	`client_secret` rotacionado	Dono da aplicação
`oauth.client.redirect_uris_updated`	Lista de redirect URIs alterada	Dono da aplicação

O mesmo event pode chegar em contas diferentes com campos contextualizados: o dono da aplicação vê resourceOwnerAccountName; a conta autorizada não recebe esse campo (já é o titular). oauth.authorization.granted:

{
  "id": "clxxx_delivery",
  "event": "oauth.authorization.granted",
  "createdAt": "2026-06-10T18:00:00.000Z",
  "data": {
    "authorizationId": "clx_auth",
    "applicationId": "clx_app",
    "applicationName": "Minha Integração",
    "clientId": "gp_oac_live_...",
    "environment": "PRODUCTION",
    "grantedScopes": ["account:read", "payments:read"],
    "resourceOwnerAccountId": "clx_merchant"
  }
}

oauth.authorization.revoked — campo reason: user, app_owner, auto ou security:

{
  "id": "clxxx_delivery",
  "event": "oauth.authorization.revoked",
  "createdAt": "2026-06-10T18:05:00.000Z",
  "data": {
    "authorizationId": "clx_auth",
    "applicationId": "clx_app",
    "applicationName": "Minha Integração",
    "clientId": "gp_oac_live_...",
    "environment": "PRODUCTION",
    "grantedScopes": ["account:read"],
    "resourceOwnerAccountId": "clx_merchant",
    "reason": "user"
  }
}

Apps de terceiros com token OAuth podem cadastrar webhooks via /v1/webhooks/* usando Authorization: Bearer gp_oat_... e scopes webhooks:read / webhooks:write. Veja o guia OAuth.

Teste

Evento	Quando ocorre
`webhook.test`	Disparo manual no dashboard.

{
  "id": "clxxx_delivery",
  "event": "webhook.test",
  "createdAt": "2026-06-10T18:00:00.000Z",
  "data": {
    "message": "Evento de teste GoatPay",
    "endpointId": "clx_webhook",
    "timestamp": "2026-06-10T18:00:00.000Z"
  }
}

Fluxos comuns

Endpoints da API

Ação	Rota
Criar	POST /webhooks/create
Listar	GET /webhooks/list
Consultar	GET /webhooks/get/
Atualizar	PATCH /webhooks/update/
Revogar	DELETE /webhooks/delete/

Permissões na API key: webhooks/create, webhooks/list, webhooks/get, webhooks/update, webhooks/delete.

Introdução

WebSocket

PIX

Conta

Loja

Subcontas

OAuth 2.0

Webhooks

Configurar

Escopo por API key

Teste

Formato da entrega

Tipos de `data`

Campos úteis em transações PIX

Segurança e assinatura

Validação (Node.js)

Retentativas

Idempotência

Checklist

Eventos

Catálogo (ativos)

PIX recebido

Estorno PIX (depósito recebido)

PIX enviado

Transferência interna

MED

Links de pagamento

Nota fiscal

OAuth 2.0

Teste

Fluxos comuns

Endpoints da API

​Configurar

​Escopo por API key

​Teste

​Formato da entrega

​Tipos de data

​Campos úteis em transações PIX

​Segurança e assinatura

​Validação (Node.js)

​Retentativas

​Idempotência

​Checklist

​Eventos

​Catálogo (ativos)

​PIX recebido

​Estorno PIX (depósito recebido)

​PIX enviado

​Transferência interna

​MED

​Links de pagamento

​Nota fiscal

​OAuth 2.0

​Teste

​Fluxos comuns

​Endpoints da API

Configurar

Escopo por API key

Teste

Formato da entrega

Tipos de `data`

Campos úteis em transações PIX

Segurança e assinatura

Validação (Node.js)

Retentativas

Idempotência

Checklist

Eventos

Catálogo (ativos)

PIX recebido

Estorno PIX (depósito recebido)

PIX enviado

Transferência interna

MED

Links de pagamento

Nota fiscal

OAuth 2.0

Teste

Fluxos comuns

Endpoints da API