Pular para o conteúdo

Webhooks

Um webhook é uma requisição HTTP que o Invoise envia ao seu servidor quando um pagamento muda. Você pode começar com verificações de status por GET e adicionar webhooks quando precisar de atualizações automáticas.

Janela do terminal
curl -X POST 'https://platform.invoise.me/api/v1/shops/{shop_id}/webhooks' \
-H 'Authorization: Bearer ivk_...' \
-H 'Idempotency-Key: <saved-unique-key>' \
-H 'Content-Type: application/json' \
-d '{"url":"https://example.com/invoise","filters":["transfer","invoice","payout"]}'

Use sua própria URL HTTPS pública. Endereços locais e privados são rejeitados. Salve o secret retornado quando o endpoint é criado: você precisa dele para verificar as requisições.

Uma loja pode ter até 10 endpoints. A URL de um endpoint pode ser alterada, então reutilize um em vez de adicionar outro. Veja Limites.

Evento Significado
transfer.observed Uma transferência foi vista; ainda não está confirmada.
transfer.confirmed Uma transferência recebida tem confirmações suficientes. Pode ser apenas um pagamento parcial da fatura.
transfer.reverted Um evento de transferência anterior foi revertido.
invoice.closed A fatura se fechou na blockchain.
invoice.cancelled A página de pagamento foi cancelada ou a fatura expirou; isso não é um reembolso.
payout.sent O repasse foi transmitido ou sua transferência de saída foi vista.
payout.confirmed A contabilização completa da liquidação está disponível.
payout.reverted Uma confirmação de repasse anterior foi revertida.
payout.failed Uma falha terminal de repasse precisa de intervenção.

Para invoice.cancelled, data.reason diz o motivo: expired quando a vida útil da fatura terminou, merchant_blocked quando a equipe do Invoise bloqueou o lojista. Um cancelamento pelo lojista, inclusive o causado por arquivar a loja, não tem reason.

Uma lista filters vazia recebe todos os eventos. Caso contrário, liste grupos (transfer, invoice, payout), tipos de evento específicos como payout.confirmed, ou ambos. Transferências recebidas e repasses de saída são eventos diferentes. Um atraso temporário de RPC ou gas não é payout.failed.

gas.wait e sweep.failed são aceitos como filtros, mas o Invoise não os envia ao seu endpoint. São sinais internos: gas.wait significa que um repasse está aguardando fundos de taxa de rede e continua por conta própria; sweep.failed significa que uma tentativa de mover os fundos ao seu destinatário falhou. Você não precisa agir em nenhum dos dois casos. Um repasse que não consegue se completar chega até você como payout.failed.

Em uma loja sandbox você pode simular os dois por POST /shops/{shop_id}/sandbox/simulate para verificar que um repasse atrasado não quebra seu fluxo. Eles alteram apenas o estado do repasse e não enviam webhook.

Invoise-Signature tem o formato t=<timestamp>,v1=<hex>. A assinatura é HMAC-SHA256 de timestamp + "." + raw_body, usando o segredo do seu webhook.

O exemplo em Node.js a seguir também rejeita timestamps com mais de cinco minutos de diferença do relógio do servidor. Mantenha esse relógio sincronizado e escolha sua tolerância deliberadamente.

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header ?? '');
if (!match) return false;
const [, timestamp, signature] = match;
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = createHmac('sha256', secret)
.update(timestamp + '.')
.update(rawBody)
.digest();
return timingSafeEqual(Buffer.from(signature, 'hex'), expected);
}

Passe os bytes originais da requisição como rawBody. Não faça parse do JSON e stringify antes de verificar a assinatura. Rejeite assinaturas inválidas antes de armazenar ou agir sobre o conteúdo.

O corpo de transfer.confirmed se parece com isto. O esquema de cada evento está na seção webhooks de openapi.json.

{
"id": "<event-id>",
"type": "transfer.confirmed",
"created_at": "2026-09-19T10:00:05Z",
"data": {
"issuance_id": "<issuance-id>",
"public_id": "<public-id>",
"shop_id": "<shop-id>",
"external_id": "customer-42",
"type": "deposit",
"family": "evm",
"chain_id": 8453,
"token": "<token-address>",
"token_decimals": 6,
"address": "<payment-address>",
"recipient": "<recipient-address>",
"invoice_cancelled": false,
"cancelled_at": null,
"direction": "incoming",
"chain_event": {
"event_id": "<transfer-id>",
"kind": "transfer.confirmed",
"chain_id": 8453,
"tx_hash": "<tx-hash>",
"log_index": 2,
"block_number": 35123456,
"block_hash": "<block-hash>",
"token": "<token-address>",
"from": "<payer-address>",
"to": "<payment-address>",
"amount": "25000000",
"confirmations": 12,
"occurred_at": "2026-09-19T10:00:00Z"
}
}
}

Para creditar um pagamento, leia data.chain_event. amount é o que chegou, em unidades base do token: divida por 10^data.token_decimals, então 25000000 com 6 casas decimais são 25 tokens. event_id identifica a transferência e tx_hash é a sua transação. data.issuance_id e data.external_id indicam a fatura ou o depósito que ela pagou. Em uma fatura, uma transferência pode ser um pagamento parcial.

Caso Tratamento
Duplicatas Deduplique usando Invoise-Event-ID, que corresponde ao id do envelope. Salve o ID e a atualização de negócio atomicamente.
Aceitar um evento Salve eventos aceitos de forma durável, retorne 2xx prontamente e processe o trabalho enfileirado depois.
Repetições e reenvios Repetições e reenvios manuais reutilizam o ID do evento. Invoise-Attempt-ID muda e não é uma chave de deduplicação.
Cabeçalhos Cada requisição traz Invoise-Event-ID e Idempotency-Key, ambos iguais ao id do evento; Invoise-Delivery-ID, um por evento e endpoint; Invoise-Attempt-ID, novo a cada tentativa; e Invoise-Signature.
Ordem dos eventos Os eventos podem chegar fora de ordem. Use seu conteúdo e reconcilie com o status atual quando necessário.

Se uma reorganização da blockchain remover uma transferência, chega transfer.reverted com chain_event.reference_event_id igual ao event_id da transferência que você creditou: estorne esse valor. payout.confirmed traz amount, o que o destinatário recebeu, e service_fee, a taxa desse repasse; em payout.sent e payout.failed ambos são null. Todo evento de repasse tem um payout_id estável e o hash da transação. incoming_transfer_ids lista as transferências cobertas pelo repasse, no máximo 100; incoming_transfers_truncated sinaliza uma lista maior.

Eventos armazenados antigos podem usar project_id; leia shop_id primeiro e use-o como alternativa se necessário. Reenvios mantêm os bytes originais.

GET /api/v1/shops/{shop_id}/deposits é o registro completo das transferências recebidas confirmadas da loja, de faturas e de depósitos, das mais recentes para as mais antigas. Não é uma lista de endereços: POST no mesmo caminho cria um endereço de depósito. Cada linha tem id, igual a chain_event.event_id do webhook, além de issuance_id, external_id, amount, tx_hash, sender e occurred_at. Percorra-o com limit e cursor para se atualizar após uma indisponibilidade ou conferir seus registros.

status no registro é sempre confirmed. Uma transferência revertida por uma reorganização some do registro, e você recebe transfer.reverted por ela.

Uma entrega tem sucesso quando o seu endpoint responde com qualquer status 2xx. Outro status, um timeout ou um erro de conexão é repetido: a primeira repetição vem após 5 segundos, e a espera dobra a cada tentativa, até no máximo uma hora entre tentativas. Após 72 horas sem um 2xx, o Invoise para e marca a entrega como failed.

Cada tentativa tem 20 segundos no total, e os cabeçalhos da sua resposta precisam chegar em até 10 segundos. Salve o evento e responda primeiro; faça o trabalho depois.

Arquivar uma loja com PATCH /api/v1/shops/{shop_id} e {"archived":true} desativa os seus endpoints de webhook. Os eventos da loja, inclusive o invoice.cancelled das suas faturas não pagas, continuam registrados, mas não são entregues.

Liste com GET /api/v1/shops/{shop_id}/deliveries. Reenvie uma entrega com POST /api/v1/shops/{shop_id}/deliveries/{id}/replay e uma chave de idempotência salva. Reenviar não cria um novo evento de negócio. Um reenvio abre uma nova janela de repetições de 72 horas; é possível reenviar uma entrega entregue ou com falha.