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"
}
}idtextoIdentificador do evento. Use para não processar o mesmo evento duas vezes.
tipotextoO evento. Veja Eventos.
sequenciainteiroCresce na ordem em que os eventos aconteceram. Use para ignorar evento atrasado.
criado_emdataQuando o evento aconteceu.
dadosobjetoA 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 }
}