Skip to main content
Webhooks permitem que você receba notificações HTTP POST quando eventos ocorrem na sua conta (pagamento confirmado, saque processado, disputa aberta, etc).

​
Configurando webhooks

Cadastre uma URL para receber eventos: 
curl -X POST https://api.linka.com/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seusite.com/webhooks/linka",
    "events": ["TRANSACTION_PAID", "TRANSACTION_FAILED", "WITHDRAWAL_COMPLETED"]
  }'

​
Formato do webhook

A Linka envia um POST para sua URL com o seguinte formato: 
{
  "event": "TRANSACTION_PAID",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "PAID",
    "amount": 1000,
    "feeAmount": 15,
    "netAmount": 985,
    "paymentMethod": "PIX",
    "paidAt": "2026-04-11T14:31:00.000Z",
    "customer": {
      "name": "Joao Silva",
      "email": "j***@email.com"
    }
  },
  "timestamp": "2026-04-11T14:31:01.000Z"
}

​
Validação de assinatura

Cada webhook inclui um header x-webhook-signature com HMAC-SHA256 do body usando seu apiSecret: 
const crypto = require('crypto');

function validateWebhook(body, signature, apiSecret) {
  const expected = crypto
    .createHmac('sha256', apiSecret)
    .update(JSON.stringify(body))
    .digest('hex');

  return `sha256=${expected}` === signature;
}

// No seu handler
app.post('/webhooks/linka', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  if (!validateWebhook(req.body, signature, process.env.LINKA_API_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Processar o evento...
  res.status(200).json({ received: true });
});
Sempre valide a assinatura antes de processar o webhook. Isso previne ataques de replay e garante que o webhook veio da Linka.

​
Retry policy

TentativaDelay
1aImediata
2a~2.5 segundos
3a~4.5 segundos
Se todas as tentativas falharem, o webhook e marcado como EXHAUSTED. Você pode reenvia-lo manualmente via POST /webhooks/resend-transaction-event.

​
Respostas esperadas

StatusSignificado
200, 201, 204Webhook recebido com sucesso
4xxWebhook não sera retentado (erro do cliente)
5xx, timeoutWebhook sera retentado

​
Boas práticas

Processe o webhook de forma assíncrona. Responda com 200 imediatamente e enfileire o processamento real.
Webhooks podem ser enviados mais de uma vez. Use o data.id como chave de idempotencia para evitar processamento duplicado.
A URL do webhook deve usar HTTPS. URLs HTTP serao rejeitadas.
Sempre valide x-webhook-signature antes de confiar no conteudo do webhook.