Copy page

Plataforma

Eventos de webhook

Esta página cataloga tipos de eventos de webhook, formatos de payload e comportamento de entrega. Para registro, cabeçalhos e segurança, comece em Webhooks. Para passos de verificação HMAC, consulte Verificação de assinatura de webhook.

Formato de envelope

Cada webhook entregue usa a mesma estrutura de nível superior:

Code
{
  "data": {
    "notification_type": "...",
    ...
  }
}

A Fluxis assina o corpo JSON parseado completo (o objeto que contém data), não apenas o objeto interno data nem bytes brutos da requisição. Campos opcionais omitidos no payload (Go omitempty) afetam a assinatura — sempre verifique contra o JSON que você realmente recebeu.

Cabeçalhos de entrega

Cabeçalho	Descrição
X-Request-Signature	HMAC-SHA256 codificado em hexadecimal
X-Request-Timestamp	Timestamp Unix (segundos)
Content-Type	application/json

Rejeite requisições com mais de 300 segundos. Consulte o guia de verificação de assinatura para o algoritmo completo.

Tipos de evento

Webhooks são registrados por conta via POST /v1/account/{accountID}/webhook. Cada registro assina um event_type:

event_type	notification_type no payload	Status de entrega
payment_request	payment_request_status_update	Ativo
refund	refund_status_update	Ativo (na criação do reembolso)
incoming_transfer	—	Reservado / futuro

---

Eventos payment_request

Assine com "event_type": "payment_request".

Quando disparam

A Fluxis envia um webhook quando o status da solicitação de pagamento muda para:

Status	Gatilho
processing	Depósito on-chain detectado; verificação de finalidade enfileirada
completed	Pagamento integral recebido
underpaid	Pagamento recebido abaixo do valor solicitado
overpaid	Pagamento recebido acima do valor solicitado

Status como pending, created, expired, failed e confirmed não disparam webhooks payment_request hoje.

Campos do payload

Code
{
  "data": {
    "notification_type": "payment_request_status_update",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "payment_request_type": "fixed",
    "external_reference_id": "order-123",
    "status": "completed",
    "point_of_sale_id": "3cc1f7ca-c017-4e7e-b00d-aca0da6e464e",
    "account_id": "c87464d1-c54a-48c3-80c9-bee4fddf593d"
  }
}

Campo	Descrição
notification_type	Sempre payment_request_status_update
payment_request_id	UUID da solicitação de pagamento Fluxis
payment_request_type	fixed, dynamic, pre_loaded ou open
external_reference_id	Sua referência de pedido (opcional; omitido se não definido)
status	Status atual da solicitação de pagamento
point_of_sale_id	POS que criou a solicitação de pagamento
account_id	Conta proprietária (opcional; omitido se não definido)

Orientação de integração

• Trate processing como "pagamento detectado" — aguarde um status terminal antes de entregar mercadorias
• Trate underpaid e overpaid conforme a configuração do seu POS; pode ser necessário emitir um reembolso
• Use external_reference_id para mapear eventos ao seu sistema de pedidos

---

Eventos refund

Assine com "event_type": "refund".

Quando disparam

Um webhook é enviado quando um reembolso é criado via POST /v1/refunds/payment-request/{paymentRequestID}. Atualizações de status adicionais (completed, failed) dispararão quando a execução on-chain de reembolsos for implementada.

Campos do payload

Code
{
  "data": {
    "notification_type": "refund_status_update",
    "refund_request_id": "123e4567-e89b-12d3-a456-426614174000",
    "payment_request_id": "aa5d6c80-0b0b-4a2a-bbc8-14a41e6245bf",
    "status": "processing",
    "amount": "50.00"
  }
}

Campo	Descrição
notification_type	Sempre refund_status_update
refund_request_id	UUID de reembolso Fluxis
payment_request_id	Solicitação de pagamento original
status	processing, completed ou failed
amount	Valor do reembolso como string decimal

---

incoming_transfer (reservado)

Assine com "event_type": "incoming_transfer".

Este tipo de evento está definido na API e pode ser registrado, mas a Fluxis não despacha webhooks incoming_transfer em código de produção hoje. Está reservado para um recurso futuro (transferências recebidas diretas não vinculadas a um fluxo de solicitação de pagamento).

---

Testar webhooks

Envie um payload de teste assinado ao seu endpoint:

Code
POST /v1/account/{accountID}/webhook/{webhookID}/test

O teste usa um corpo de amostra payment_request_status_update. Verifique com o mesmo algoritmo dos eventos de produção — consulte Verificação de assinatura de webhook.

Matriz status → webhook

Status da solicitação de pagamento	Webhook enviado?
pending	Não
created	Não
processing	Sim
completed	Sim
underpaid	Sim
overpaid	Sim
confirmed	Não
expired	Não
failed	Não

Documentação relacionada

• Webhooks — registro, segredos, boas práticas
• Verificação de assinatura de webhook — verificação HMAC-SHA256
• Solicitações de pagamento — ciclo de vida completo de status
• Reembolsos — API de reembolsos e status