Copy page

Desenvolvedores

Webhooks

A Fluxis usa webhooks em nível de conta para notificar sua aplicação em tempo real quando eventos ocorrem, como mudanças de status de pagamento. Este guia cobre registro, comportamento de entrega e um resumo da verificação de assinatura.

Para o passo a passo completo de verificação HMAC (JSON canônico, exemplo prático, endpoint de teste), consulte Verificação de assinatura de webhook.

Visão geral

Quando você registra um webhook para uma conta, a Fluxis envia requisições HTTP POST à sua URL sempre que eventos correspondentes ocorrem. Cada requisição inclui:

• Um payload JSON com dados do evento
• Cabeçalhos de segurança para verificação de assinatura

Cabeçalhos de webhook

Cada requisição de webhook inclui os seguintes cabeçalhos:

Cabeçalho	Descrição
X-Request-Signature	Assinatura HMAC-SHA256 do payload
X-Request-Timestamp	Timestamp Unix (segundos) quando a requisição foi gerada
Content-Type	Sempre application/json

Registrar webhooks

Webhooks são gerenciados em nível de conta (não por Ponto de Venda). Use as credenciais da organização para registrar um endpoint HTTPS para a conta vinculada ao seu POS.

Criar webhook: POST /v1/account/{accountID}/webhook

Code
{
  "url": "https://your-server.com/webhooks/fluxis",
  "event_type": "payment_request",
  "description": "Order status updates"
}

A resposta inclui um secret — armazene-o imediatamente; ele só é retornado na criação.

event_type	Quando dispara
payment_request	Mudanças de status da solicitação de pagamento (veja abaixo)
incoming_transfer	Eventos de transferência recebida (reservado / uso futuro)
refund	Eventos de reembolso

Outros endpoints de gerenciamento:

Ação	Endpoint
List	GET /v1/account/{accountID}/webhook/list
Update URL	PUT /v1/account/{accountID}/webhook/{webhookID}/url
Activate	PATCH /v1/account/{accountID}/webhook/{webhookID}/activate
Deactivate	PATCH /v1/account/{accountID}/webhook/{webhookID}/deactivate
Delete	DELETE /v1/account/{accountID}/webhook/{webhookID}/delete
Test delivery	POST /v1/account/{accountID}/webhook/{webhookID}/test
Delivery logs	GET /v1/account/{accountID}/webhook/logs?page=1&page_size=20

Consulte a Referência API — Webhooks.

---

Verificar assinaturas de webhook (resumo)

A Fluxis assina o corpo JSON parseado completo — por exemplo { "data": { … } } — não os bytes brutos da requisição nem apenas o objeto interno data.

Algoritmo:

1. Serialize o corpo parseado em JSON canônico (compacto, chaves ordenadas alfabeticamente em cada nível de objeto)
2. Monte a string assinada: <unix_timestamp>.<canonical_json>
3. Calcule HMAC-SHA256(webhook_secret, signed_string) e codifique o resultado em hexadecimal
4. Compare com X-Request-Signature usando função de tempo constante
5. Rejeite se o timestamp tiver mais de 300 segundos (5 minutos)

Exemplo de string assinada (timestamp 1712345678, payload de amostra payment_request):

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

::::note Campos opcionais Campos como external_reference_id e account_id usam omitempty na API — são omitidos do JSON quando não definidos. Seu verificador deve canonicalizar o corpo parseado como recebido, não um template de esquema fixo. ::::

Verificação rápida em Node.js (consulte o guia completo para Python, Go e um exemplo prático):

Code
import crypto from "crypto";

function sortKeys(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(sortKeys);
  if (value !== null && typeof value === "object") {
    return Object.keys(value as object)
      .sort()
      .reduce((acc, key) => {
        acc[key] = sortKeys((value as Record<string, unknown>)[key]);
        return acc;
      }, {} as Record<string, unknown>);
  }
  return value;
}

function verifyWebhookSignature(
  payload: unknown,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  const requestTimestamp = parseInt(timestamp, 10);
  if (Math.floor(Date.now() / 1000) - requestTimestamp > 300) return false;

  const canonicalJson = JSON.stringify(sortKeys(payload));
  const signedString = `${timestamp}.${canonicalJson}`;
  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(signedString)
    .digest("hex");

  if (signature.length !== expectedSignature.length) return false;
  return crypto.timingSafeEqual(
    Buffer.from(signature, "utf8"),
    Buffer.from(expectedSignature, "utf8"),
  );
}

---

Quais status disparam webhooks

A Fluxis entrega webhooks payment_request quando uma solicitação de pagamento entra em processing (pagamento detectado) ou um estado terminal de confirmação (completed, underpaid ou overpaid).

Mudanças de status como expired ou failed não são enviadas via webhook — faça polling do endpoint de solicitação de pagamento ou concilie via transações.

Estrutura do payload de webhook

Webhooks de atualização de status de solicitação de pagamento têm a seguinte estrutura:

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

Campo	Descrição
notification_type	Tipo de notificação (ex.: payment_request_status_update)
payment_request_id	Identificador único da solicitação de pagamento
payment_request_type	Tipo de solicitação de pagamento (ex.: fixed)
external_reference_id	Seu ID de referência interna (opcional; omitido se não definido)
status	Novo status da solicitação de pagamento
point_of_sale_id	ID do Ponto de Venda
account_id	ID da conta associada (opcional; omitido se não definido)

---

Boas práticas

Responder rapidamente

Seu endpoint deve retornar HTTP 200 OK em 2 segundos. Se precisar de processamento pesado, confirme o webhook imediatamente e enfileire o trabalho para execução em segundo plano.

Code
app.post("/webhooks/fluxis", async (req, res) => {
  if (!verifyWebhookSignature(req.body, /* ... */)) {
    return res.status(401).send();
  }
  res.status(200).json({ received: true });
  processWebhookAsync(req.body).catch(console.error);
});

Tratar duplicatas (idempotência)

Você pode receber o mesmo evento de webhook várias vezes. Use payment_request_id e status para deduplicar.

Consciência de lógica de retry

Se seu endpoint não responder com HTTP 200, a Fluxis pode reenviar o webhook. Garanta que seu handler seja idempotente.

---

Testar webhooks

1. Exponha seu servidor local com ngrok ou similar durante o desenvolvimento.
2. Registre a URL pública via POST /v1/account/{accountID}/webhook.
3. Dispare uma entrega de teste: POST /v1/account/{accountID}/webhook/{webhookID}/test — usa o mesmo caminho de assinatura da produção.
4. Confirme que seu handler verifica a assinatura e retorna HTTP 200.

Consulte Verificação de assinatura de webhook para verificação passo a passo e falhas comuns.

---

Solução de problemas

Problema	O que verificar
Assinatura falha	Segredo correto da resposta de criação; assinar o corpo parseado {data:…}; regras de JSON canônico — guia completo
Não recebe eventos	URL HTTPS pública; HTTP 200 em 2 s; webhook habilitado; event_type correto
Faltam webhooks expired / failed	Esperado — faça polling de GET /v1/pos/{posID}/payment-request/{paymentRequestID}

---

Precisa de ajuda?

Entre em contato em [email protected] com o ID da conta, ID do webhook e timestamp da entrega problemática.