Worldfy PaymentsWorldfy Payments
SuporteDashboard
GuiaAPI Reference
SuporteDashboard

Começando

IntroduçãoAutenticaçãoErrosPaginação e Filtros
Cobranças
Visão GeralMétodos de PagamentoCaptura e Estorno
Financeiro
RecebíveisAntecipaçõesCarteiras e ExtratosSaques
Configuração
Chaves de APIRecebedores
SDK de Segurança
Visão geralTokenizaçãoAutenticação 3DSAnálise de fraudeFluxo simplificadoFluxo completoErrosProdução e segurança
Webhooks
Visão GeralConfiguraçãoRetentativas
Eventos
Eventos de CobrançasEventos de Saques

Visão Geral

Entenda como o sistema de webhooks da Worldfy funciona e como receber notificações em tempo real sobre eventos da sua conta.

Retentativas

Política de retentativas, backoff exponencial e boas práticas para garantir a entrega confiável de webhooks.

Webhooks

Configuração

Como criar endpoints de webhook, gerenciar secrets e validar assinaturas HMAC-SHA256 para garantir a autenticidade das notificações.

Criando um endpoint

Para receber notificações, crie um endpoint de webhook pelo painel ou via API:

curl -X POST https://api.worldfypayments.com/v1/postbacks/endpoints \
  -H "Authorization: Basic {credentials}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meusite.com/webhooks",
    "events": ["charge.captured", "charge.refunded", "charge.failed"]
  }'

A resposta inclui o secret do endpoint, que será exibido apenas uma vez:

{
  "data": {
    "id": "uuid-do-endpoint",
    "url": "https://meusite.com/webhooks",
    "secret": "a1b2c3d4e5f6...",
    "events": ["charge.captured", "charge.refunded", "charge.failed"],
    "status": "active",
    "created_at": "2026-02-24T10:00:00.000Z"
  }
}

Copie e guarde o secret imediatamente. Ele não será exibido novamente. Se perder, será necessário regenerar.

Gerenciando endpoints

Cada endpoint pode ser atualizado individualmente:

  • Alterar URL: PATCH /v1/postbacks/endpoints/{id} com { "url": "nova-url" }
  • Alterar eventos: PATCH /v1/postbacks/endpoints/{id} com { "events": ["charge.captured"] }
  • Pausar/ativar: PATCH /v1/postbacks/endpoints/{id} com { "status": "paused" } ou { "status": "active" }
  • Remover: DELETE /v1/postbacks/endpoints/{id}

Segurança: assinatura HMAC-SHA256

Toda notificação inclui o header X-Worldfy-Signature com uma assinatura HMAC-SHA256 do corpo da requisição. Use essa assinatura para verificar que a notificação realmente veio da Worldfy.

Cada endpoint tem seu próprio secret, gerado automaticamente na criação. Você pode regenerar o secret a qualquer momento via POST /v1/postbacks/endpoints/{id}/secret/regenerate.

Validando a assinatura

Receba o header X-Worldfy-Signature

O valor segue o formato sha256=<hex>.

Compute o HMAC do corpo da requisição

Use o secret do endpoint como chave.

Compare as assinaturas

Use comparação em tempo constante para evitar timing attacks.

Exemplos de validação

const crypto = require('crypto');

function validateSignature(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  const received = signature.replace('sha256=', '');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(received)
  );
}

// Uso no Express
app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-worldfy-signature'];
  const isValid = validateSignature(
    JSON.stringify(req.body),
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Processar evento...
  res.status(200).send('OK');
});
import hmac
import hashlib

def validate_signature(body: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body.encode(),
        hashlib.sha256
    ).hexdigest()

    received = signature.replace('sha256=', '')
    return hmac.compare_digest(expected, received)
function validateSignature(string $body, string $signature, string $secret): bool
{
    $expected = hash_hmac('sha256', $body, $secret);
    $received = str_replace('sha256=', '', $signature);
    return hash_equals($expected, $received);
}

Nunca exponha o secret em código client-side ou repositórios públicos. Trate-o como uma credencial sensível.

Visão Geral

Entenda como o sistema de webhooks da Worldfy funciona e como receber notificações em tempo real sobre eventos da sua conta.

Retentativas

Política de retentativas, backoff exponencial e boas práticas para garantir a entrega confiável de webhooks.

On this page

Criando um endpointGerenciando endpointsSegurança: assinatura HMAC-SHA256Validando a assinaturaReceba o header X-Worldfy-SignatureCompute o HMAC do corpo da requisiçãoCompare as assinaturasExemplos de validação