Eventos | Quibly Pay

A fila de saída de pagamentos emite transaction.paid para transações DEPOSIT e WITHDRAW pagas. Esta referência não garante outros eventos de pagamento enviados.

Destinos das entregas:

Webhooks cadastrados em Desenvolvedor > Webhooks recebem os eventos selecionados para transações PRODUCTION.
Destinos por cobrança, em SANDBOX e PRODUCTION: o urlnoty enviado ao criar a cobrança e a URL de webhook da chave de API. Eles usam o webhook marcado "Usar nas notificações por cobrança", que deve estar ativo e é único por conta. Sem webhook marcado, ou enquanto ele estiver pausado, uma credencial criada antes de 2026-10-05 que ainda tenha o segredo legado whsec_ continua assinando com ele, apenas por assinatura; caso contrário, nenhuma entrega é criada. Marcar um webhook faz essas entregas usarem o segredo e a chave de assinatura dele; atualize o receptor antes. Sem chave, nada é enviado.
Se um webhook cadastrado e um destino por cobrança tiverem a mesma URL normalizada, ocorre uma única entrega, como webhook cadastrado.

Dois valores diferentes protegem a entrega:

Segredo do webhook: definido por você, com 16 a 128 caracteres ASCII imprimíveis e sem espaços, ou gerado uma única vez. Ele é enviado no header X-Quibly-Secret. Compare-o com o segredo armazenado em tempo constante. Só é enviado para a URL do webhook cadastrado e para URLs por cobrança com exatamente a mesma origem (esquema, host e porta) do webhook marcado. Outras origens, como uma URL de automação de terceiros, não o recebem e devem verificar a assinatura. Entregas legadas com whsec_ nunca incluem esse header.
Chave de assinatura: uma chave própria de cada webhook (whsig_...), usada apenas na assinatura HMAC opcional. Revele-a em Desenvolvedor > Webhooks > Avançado: chave de assinatura, com confirmação por dois fatores, e faça a rotação nesse mesmo local. Webhooks criados antes de 2026-10-05 assinam com o próprio segredo até a rotação da chave de assinatura; faça a rotação para separar os dois valores. Para entregas legadas com whsec_, a chave de assinatura é o valor whsec_ completo.

Alterar o segredo ou rotacionar a chave de assinatura também afeta as retentativas já enfileiradas. Nenhum desses valores é client_secret.

Após verificar a entrega, elimine duplicatas de X-Quibly-Event-Id de forma atômica em armazenamento durável. Garanta também uma única entrega do produto por transactionId, pois destinos diferentes podem ter IDs de entrega distintos para a mesma transação. Consulte /transaction com suas credenciais, verifique PAID e o valor/pedido esperado, salve ou enfileire o trabalho e retorne 2xx prontamente. Se a consulta falhar, permita uma nova tentativa; nunca marque o evento como processado antes de salvar seu trabalho com segurança. Eventos duplicados já processados com sucesso devem retornar 2xx.

Qualquer 2xx indica sucesso. A entrega tem um prazo total de 15 segundos. Há até cinco tentativas automáticas: imediata, depois com intervalos de 60, 300, 900 e 3600 segundos após as falhas. Respostas fora de 2xx ou erros de rede geram retentativas até esgotar o limite. O reenvio manual preserva o ID do evento. Destinos excluídos, desabilitados ou alterados podem cancelar entregas pendentes; chaves de API revogadas invalidam os destinos vinculados a elas.