Webhooks

Como funcionam

Webhook é um aviso que a Grinny Pay manda para o seu servidor quando algo acontece: Pix gerado, Pix pago, MED aberto, saque concluído. Assim você não precisa ficar consultando a API.

Como cadastrar

  • No painel, em Integrações › Webhooks (pede a verificação em duas etapas). Até 5 webhooks por conta.
  • A URL precisa ser https na porta padrão (443), com um domínio (não vale IP digitado nem localhost), até 500 caracteres.
  • Escolha os eventos que quer receber. Veja Eventos.
  • Ao criar, aparece o segredo do webhook (começa com whsec_) uma única vez. Guarde: é com ele que você confere a assinatura.

O que chega no seu servidor

Um POST com o corpo em JSON e estes cabeçalhos:

POST /seu/endereco HTTP/1.1
Content-Type: application/json
User-Agent: GrinnyPay-Webhook/1
X-Grinny-Event: venda.aprovada
X-Grinny-Signature: t=1760549530,v1=5f2b8c...e91a
{
  "id": "evt_5821",
  "tipo": "venda.aprovada",
  "sequencia": 5821,
  "criado_em": "2026-10-15T14:32:10-03:00",
  "dados": {
    "id": "8f2c4b1e9a7d4c3b8e1f2a3b4c5d6e7f",
    "status": "pago",
    "valor": 9700,
    "...": "o mesmo objeto cobrança da API"
  }
}
idtexto

Identificador do evento. Use para não processar o mesmo evento duas vezes.

tipotexto

O evento. Veja Eventos.

sequenciainteiro

Cresce na ordem em que os eventos aconteceram. Use para ignorar evento atrasado.

criado_emdata

Quando o evento aconteceu.

dadosobjeto

A cobrança, o saque ou o MED como estava no momento do evento (mesmo numa nova tentativa de entrega).

Como responder

  • Responda com qualquer status 2xx em até 5 segundos. Só isso conta como entregue.
  • Faça o trabalho pesado depois de responder (por exemplo, numa fila).
  • Lemos no máximo 64 KB da sua resposta: não precisa mandar corpo.

Novas tentativas

Se o seu servidor não responder 2xx a tempo, tentamos de novo depois de cerca de 1 min, 5 min, 15 min, 1 h, 3 h, 6 h e 12 h. São 8 tentativas no total (a primeira e mais 7). Depois disso, o envio fica como falhou e você pode reenviar pelo painel. Detalhes em Entrega e reenvio.

As entregas podem chegar fora de ordem e repetidas. Guarde o id dos eventos já processados e, para a mesma cobrança, ignore evento com sequencia menor que a do último que você processou. Exemplo: um venda.expirada atrasado chegando depois do venda.aprovada.

Testar

O botão Testar do painel manda um evento teste.ping (sem sequencia) para a sua URL. Ele não tenta de novo sozinho.

{
  "id": "evt_5830",
  "tipo": "teste.ping",
  "criado_em": "2026-10-15T14:50:00-03:00",
  "dados": { "mensagem": "Envio de teste da Grinny Pay. Pode ignorar.", "webhook": 12 }
}