Webhooks

Webhooks são notificações HTTP que a Linka envia para sua aplicação quando ocorrem eventos importantes, como uma transação paga, um saque liquidado ou uma disputa aberta. Em vez de fazer polling na API, você configura uma URL e recebe os eventos em tempo real.

Como funciona

Você cadastra uma URL HTTPS na tela de Integrações > Webhooks (ou via POST /v1/webhooks)
Quando um evento ocorre, a Linka envia um POST com payload JSON
Seu servidor deve responder 2xx em até 5 segundos
Sem resposta ou com erro 5xx, a Linka retenta automaticamente (veja Comportamento de Retry)

A URL do webhook precisa ser HTTPS. URLs HTTP são rejeitadas.

Anatomia de uma entrega

Cada entrega inclui dois headers e um payload JSON com os campos do recurso no nível raiz:

Onde	Campo	Descrição
Header	`X-Delivery-Id`	Identificador estável da entrega — use para deduplicar reentregas
Header	`X-Webhook-Timestamp`	Timestamp (ms) do momento da entrega — entra no cálculo da assinatura
Body	`version`	Versão do payload (`"1"`)
Body	`expires_at`	Validade da entrega (24h) — rejeite entregas após esta data
Body	`eventType`	Nome do evento (ex: `TRANSACTION_PAID`)
Body	`signature`	Assinatura HMAC no formato `v1=<base64url>`
Body	demais campos	Dados do recurso (transação, saque ou disputa), no nível raiz

Validando a assinatura

A assinatura é enviada no campo signature do body (não em header). Ela é um HMAC-SHA256 calculado sobre a string "<timestamp>.<json_do_evento>", onde:

<timestamp> é o valor do header X-Webhook-Timestamp;
<json_do_evento> é o JSON do payload sem os campos version, expires_at e signature, preservando a ordem das chaves recebidas e sem espaços;
o resultado é codificado como v1= + Base64URL (sem = de padding).

Além de comparar a assinatura, rejeite entregas cujo timestamp esteja a mais de 5 minutos do relógio atual (janela anti-replay).

import crypto from 'crypto';

// Importante: use o corpo cru (raw body) parseado uma única vez.
app.post('/webhooks/linka', express.json(), (req, res) => {
  const timestamp = req.headers['x-webhook-timestamp'];
  const { version, expires_at, signature, ...event } = req.body;

  // 1. Janela anti-replay de 5 minutos
  if (Math.abs(Date.now() - Number(timestamp)) > 5 * 60 * 1000) {
    return res.status(401).json({ error: 'Timestamp fora da janela' });
  }

  // 2. Recalcula a assinatura sobre "<timestamp>.<json_do_evento>"
  const signedString = `${timestamp}.${JSON.stringify(event)}`;
  const expected = 'v1=' + crypto
    .createHmac('sha256', process.env.LINKA_WEBHOOK_SECRET)
    .update(signedString, 'utf8')
    .digest('base64url');

  const ok = signature &&
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!ok) {
    return res.status(401).json({ error: 'Assinatura inválida' });
  }

  // 3. Deduplique pelo X-Delivery-Id antes de processar
  // processarEvento(event);
  res.status(200).json({ received: true });
});

import base64
import hmac
import hashlib
import json
import time

@app.route('/webhooks/linka', methods=['POST'])
def webhook():
    timestamp = request.headers.get('X-Webhook-Timestamp', '')
    body = request.get_json()

    # 1. Janela anti-replay de 5 minutos
    if abs(time.time() * 1000 - float(timestamp)) > 5 * 60 * 1000:
        return {'error': 'Timestamp fora da janela'}, 401

    # 2. Recalcula a assinatura sobre "<timestamp>.<json_do_evento>"
    event = {k: v for k, v in body.items() if k not in ('version', 'expires_at', 'signature')}
    event_json = json.dumps(event, separators=(',', ':'), ensure_ascii=False)
    signed_string = f'{timestamp}.{event_json}'
    digest = hmac.new(WEBHOOK_SECRET.encode(), signed_string.encode(), hashlib.sha256).digest()
    expected = 'v1=' + base64.urlsafe_b64encode(digest).decode().rstrip('=')

    if not hmac.compare_digest(expected, body.get('signature', '')):
        return {'error': 'Assinatura inválida'}, 401

    # 3. Deduplique pelo X-Delivery-Id antes de processar
    return {'received': True}, 200

O secret usado na validação é o secret retornado uma única vez na criação do webhook. Se você rotacionar o secret (POST /v1/webhooks/{id}/rotate-secret), atualize sua aplicação imediatamente.

Configurando um Endpoint de Webhook

Crie um endpoint HTTPS no seu servidor

O endpoint deve estar acessível publicamente via HTTPS e retornar HTTP 200 para confirmação.

Registre o webhook na Linka

curl -X POST https://api.linkagateway.com/v1/webhooks \
  -H "x-api-key: {sua_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://seu-sistema.com.br/webhooks/linka",
    "description": "Webhook de produção",
    "eventType": "ALL"
  }'

const response = await fetch('https://api.linkagateway.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://seu-sistema.com.br/webhooks/linka',
    description: 'Webhook de produção',
    eventType: 'ALL',
  }),
});

const { data: webhook } = await response.json();

const response = await fetch('https://api.linkagateway.com/v1/webhooks', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://seu-sistema.com.br/webhooks/linka',
    description: 'Webhook de produção',
    eventType: 'ALL',
  }),
});

const { data: webhook } = await response.json() as any;

import requests

response = requests.post(
    'https://api.linkagateway.com/v1/webhooks',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json',
    },
    json={
        'url': 'https://seu-sistema.com.br/webhooks/linka',
        'description': 'Webhook de produção',
        'eventType': 'ALL',
    },
)

webhook = response.json()['data']

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body := map[string]string{
        "url":         "https://seu-sistema.com.br/webhooks/linka",
        "description": "Webhook de produção",
        "eventType":   "ALL",
    }
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", "https://api.linkagateway.com/v1/webhooks", bytes.NewBuffer(jsonBody))
    req.Header.Set("x-api-key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Println(data)
}

Resposta 201

{
  "id": "webhook_uuid",
  "url": "https://seu-sistema.com.br/webhooks/linka",
  "eventType": "ALL",
  "secret": "a3f8c2d1e9b4...",
  "isActive": true,
  "createdAt": "2026-04-09T12:00:00.000Z"
}

O campo secret é exibido apenas nesta resposta. Salve-o imediatamente, ele não será exibido novamente. Use este secret para validar a assinatura HMAC de todos os webhooks recebidos.

Implemente a validação de assinatura

Use o código da seção Validando a assinatura acima. Rejeite qualquer entrega com assinatura inválida ou timestamp fora da janela de 5 minutos.

Tipos de Evento

O campo eventType aparece em dois contextos diferentes:

No cadastro do webhook: define a categoria de eventos assinada (TRANSACTION, WITHDRAWAL, DISPUTE ou ALL).
No payload de cada entrega: identifica o evento específico (ex: TRANSACTION_PAID).

`eventType` no cadastro	Eventos recebidos
`TRANSACTION`	Todos os `TRANSACTION_*`
`WITHDRAWAL`	Todos os `WITHDRAWAL_*`
`DISPUTE`	Todos os `DISPUTE_` e `MED_DISPUTE_`
`ALL`	Todos os eventos acima

Os eventos de transação e saque seguem o padrão TRANSACTION_<STATUS> e WITHDRAWAL_<STATUS> — um evento para cada mudança de status do recurso. Trate nomes de evento desconhecidos com um fallback: novos status geram novos eventos automaticamente.

Eventos de Transação

Além dos exemplos abaixo, qualquer mudança de status gera o evento correspondente (TRANSACTION_PROCESSING, TRANSACTION_AUTHORIZED, TRANSACTION_REFUSED, TRANSACTION_CHARGEDBACK, TRANSACTION_DISPUTE, TRANSACTION_PARTIALLY_REFUNDED, entre outros).

TRANSACTION_CREATED

Disparado após a criação da transação, quando o provedor confirma a geração da cobrança.

{
  "version": "1",
  "expires_at": "2026-04-10T12:00:00.000Z",
  "eventType": "TRANSACTION_CREATED",
  "signature": "v1=K7gNU3sdo-OL0wNhqoVWhr3g6s1xYv72ol_pe_Unols",
  "id": "txn_uuid",
  "amount": 15000,
  "method": "PIX",
  "status": "PENDING",
  "description": "Pedido #123",
  "installments": 1,
  "metadata": { "orderId": "order-abc" },
  "pix": null,
  "boleto": null,
  "card": null,
  "customer": { "name": "Joao S.", "email": "jo***@email.com" },
  "createdAt": "2026-04-09T12:00:00.000Z"
}

TRANSACTION_WAITING_PAYMENT

Disparado quando o instrumento de pagamento foi gerado e aguarda o pagador.

{
  "version": "1",
  "expires_at": "2026-04-10T12:00:00.000Z",
  "eventType": "TRANSACTION_WAITING_PAYMENT",
  "signature": "v1=...",
  "id": "txn_uuid",
  "amount": 15000,
  "method": "PIX",
  "status": "WAITING_PAYMENT",
  "pix": {
    "copyPaste": "00020126580014br.gov.bcb.pix...",
    "expirationDate": "2026-04-09T13:00:00.000Z"
  },
  "createdAt": "2026-04-09T12:00:00.000Z"
}

TRANSACTION_PAID

Pagamento confirmado. O crédito já foi processado na sua wallet.

{
  "version": "1",
  "expires_at": "2026-04-10T12:05:00.000Z",
  "eventType": "TRANSACTION_PAID",
  "signature": "v1=...",
  "id": "txn_uuid",
  "amount": 15000,
  "method": "PIX",
  "status": "PAID",
  "end2endId": "E12345678202604091200...",
  "paidAt": "2026-04-09T12:05:00.000Z",
  "description": "Pedido #123",
  "installments": 1,
  "metadata": { "orderId": "order-abc" },
  "pix": { "copyPaste": "00020126...", "expirationDate": "..." },
  "boleto": null,
  "card": null,
  "payer": { "name": "Maria O.", "document": "123.***.45" },
  "customer": { "name": "Joao S.", "email": "jo***@email.com" },
  "items": [],
  "createdAt": "2026-04-09T12:00:00.000Z"
}

TRANSACTION_FAILED

Falha técnica ou erro sem mapeamento no processamento do pagamento.

{
  "version": "1",
  "expires_at": "2026-04-10T12:00:00.000Z",
  "eventType": "TRANSACTION_FAILED",
  "signature": "v1=...",
  "id": "txn_uuid",
  "amount": 15000,
  "method": "PIX",
  "status": "FAILED",
  "description": "Pedido #456",
  "createdAt": "2026-04-09T12:00:00.000Z"
}

TRANSACTION_EXPIRED

QR Code PIX vencido sem pagamento.

{
  "version": "1",
  "expires_at": "2026-04-10T12:00:00.000Z",
  "eventType": "TRANSACTION_EXPIRED",
  "signature": "v1=...",
  "id": "txn_uuid",
  "amount": 15000,
  "method": "PIX",
  "status": "EXPIRED",
  "createdAt": "2026-04-09T12:00:00.000Z"
}

TRANSACTION_REFUNDED

Estorno total processado. Em estornos parciais, o evento é TRANSACTION_PARTIALLY_REFUNDED com refundType: "PARTIAL".

{
  "version": "1",
  "expires_at": "2026-04-10T12:00:00.000Z",
  "eventType": "TRANSACTION_REFUNDED",
  "signature": "v1=...",
  "id": "txn_uuid",
  "amount": 15000,
  "method": "PIX",
  "status": "REFUNDED",
  "refundedAmount": 15000,
  "refundType": "FULL",
  "createdAt": "2026-04-09T12:00:00.000Z"
}

Eventos de Saque

Seguem o padrão WITHDRAWAL_<STATUS>: WITHDRAWAL_CREATED, WITHDRAWAL_APPROVED, WITHDRAWAL_PROCESSING, WITHDRAWAL_PAID, WITHDRAWAL_REJECTED, WITHDRAWAL_FAILED, WITHDRAWAL_REFUNDED.

WITHDRAWAL_PROCESSING

O saque está sendo processado pela instituição de pagamento.

{
  "version": "1",
  "expires_at": "2026-04-10T12:00:00.000Z",
  "eventType": "WITHDRAWAL_PROCESSING",
  "signature": "v1=...",
  "id": "wd_uuid",
  "amount": 50000,
  "method": "PIX",
  "pixKey": "jo***@email.com",
  "pixKeyType": "EMAIL",
  "status": "PROCESSING",
  "createdAt": "2026-04-09T12:00:00.000Z"
}

WITHDRAWAL_PAID

Transferência liquidada — o valor foi enviado ao destinatário.

{
  "version": "1",
  "expires_at": "2026-04-10T12:01:05.000Z",
  "eventType": "WITHDRAWAL_PAID",
  "signature": "v1=...",
  "id": "wd_uuid",
  "amount": 50000,
  "method": "PIX",
  "pixKey": "jo***@email.com",
  "pixKeyType": "EMAIL",
  "status": "PAID",
  "approvedAt": "2026-04-09T12:01:00.000Z",
  "processedAt": "2026-04-09T12:01:05.000Z",
  "end2end": "E12345678202604091201...",
  "externalRef": "ref-provider-123",
  "metadata": null,
  "destinationAccount": {
    "bankCode": "***",
    "agency": "***",
    "account": "***"
  },
  "createdAt": "2026-04-09T12:00:00.000Z"
}

WITHDRAWAL_REJECTED

Saque rejeitado. O valor debitado (incluindo a tarifa) é reembolsado automaticamente para a wallet.

{
  "version": "1",
  "expires_at": "2026-04-10T12:00:00.000Z",
  "eventType": "WITHDRAWAL_REJECTED",
  "signature": "v1=...",
  "id": "wd_uuid",
  "amount": 50000,
  "method": "PIX",
  "pixKey": "jo***@email.com",
  "pixKeyType": "EMAIL",
  "status": "REJECTED",
  "createdAt": "2026-04-09T12:00:00.000Z"
}

WITHDRAWAL_FAILED

Falha na transferência. O valor debitado (incluindo a tarifa) é reembolsado automaticamente para a wallet.

{
  "version": "1",
  "expires_at": "2026-04-10T12:00:00.000Z",
  "eventType": "WITHDRAWAL_FAILED",
  "signature": "v1=...",
  "id": "wd_uuid",
  "amount": 50000,
  "method": "PIX",
  "pixKey": "jo***@email.com",
  "pixKeyType": "EMAIL",
  "status": "FAILED",
  "createdAt": "2026-04-09T12:00:00.000Z"
}

Eventos de Disputa

DISPUTE_CREATED

Disputa aberta (chargeback ou contestação recebida).

{
  "version": "1",
  "expires_at": "2026-04-10T14:00:00.000Z",
  "eventType": "DISPUTE_CREATED",
  "signature": "v1=...",
  "id": "dispute_uuid",
  "amount": 15000,
  "status": "OPEN",
  "reason": "Fraude",
  "metadata": null,
  "createdAt": "2026-04-09T14:00:00.000Z"
}

DISPUTE_RESOLVED

Decisão a seu favor, saldo restaurado.

{
  "version": "1",
  "expires_at": "2026-04-10T14:00:00.000Z",
  "eventType": "DISPUTE_RESOLVED",
  "signature": "v1=...",
  "id": "dispute_uuid",
  "amount": 15000,
  "status": "RESOLVED",
  "createdAt": "2026-04-09T14:00:00.000Z"
}

DISPUTE_REJECTED

Decisão a favor do comprador, valor debitado permanentemente.

{
  "version": "1",
  "expires_at": "2026-04-10T14:00:00.000Z",
  "eventType": "DISPUTE_REJECTED",
  "signature": "v1=...",
  "id": "dispute_uuid",
  "amount": 15000,
  "status": "REJECTED",
  "createdAt": "2026-04-09T14:00:00.000Z"
}

MED_DISPUTE_CREATED

Disputa MED (Mecanismo Especial de Devolução) do PIX aberta.

{
  "version": "1",
  "expires_at": "2026-04-10T14:30:00.000Z",
  "eventType": "MED_DISPUTE_CREATED",
  "signature": "v1=...",
  "id": "med_dispute_uuid",
  "status": "OPEN",
  "amount": 15000,
  "transactionId": "txn_uuid",
  "deadline": "2026-04-16T23:59:59.000Z",
  "end2EndId": "E12345678202604091200...",
  "createdAt": "2026-04-09T14:30:00.000Z"
}

MED_DISPUTE_REFUND_COMPLETED

Devolução MED concluída após decisão favorável ao cliente.

{
  "version": "1",
  "expires_at": "2026-04-10T15:00:00.000Z",
  "eventType": "MED_DISPUTE_REFUND_COMPLETED",
  "signature": "v1=...",
  "id": "med_dispute_uuid",
  "status": "OPEN",
  "amount": 15000,
  "transactionId": "txn_uuid",
  "createdAt": "2026-04-09T14:30:00.000Z"
}

Comportamento de Retry

Cada ciclo de entrega faz até 3 tentativas com backoff exponencial (a partir de ~1s, dobrando até o teto de 30s, com jitter). O timeout de cada tentativa é de 5 segundos.

Resposta do seu servidor	Comportamento
`2xx`	Entrega confirmada
`4xx` (exceto `429`)	Não retenta — tratado como erro de configuração do seu endpoint
`429`	Respeita o seu `Retry-After` (até 30s) dentro do mesmo ciclo
`5xx` / timeout / erro de rede	Retenta com backoff

Se o ciclo esgotar as 3 tentativas, o evento é reenfileirado automaticamente para novos ciclos de entrega ao longo das horas seguintes, e a entrega expira após o expires_at (24h).

Após 10 falhas consecutivas, o webhook é desativado automaticamente (isActive: false) e você é notificado. Reative-o na tela de Integrações após corrigir o endpoint.

Reenviando Eventos Manualmente

Use os endpoints de reenvio para forçar a reentrega de eventos específicos:

curl -X POST https://api.linkagateway.com/v1/webhooks/resend-transaction-event \
  -H "x-api-key: {sua_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionIds": ["txn_uuid_1", "txn_uuid_2"]
  }'

const response = await fetch('https://api.linkagateway.com/v1/webhooks/resend-transaction-event', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    transactionIds: ['txn_uuid_1', 'txn_uuid_2'],
  }),
});

const { data } = await response.json();

import requests

response = requests.post(
    'https://api.linkagateway.com/v1/webhooks/resend-transaction-event',
    headers={
        'x-api-key': api_key,
        'Content-Type': 'application/json',
    },
    json={
        'transactionIds': ['txn_uuid_1', 'txn_uuid_2'],
    },
)

data = response.json()['data']

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body := map[string]interface{}{
        "transactionIds": []string{"txn_uuid_1", "txn_uuid_2"},
    }
    jsonBody, _ := json.Marshal(body)

    req, _ := http.NewRequest("POST", "https://api.linkagateway.com/v1/webhooks/resend-transaction-event", bytes.NewBuffer(jsonBody))
    req.Header.Set("x-api-key", apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    var data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    fmt.Println(data)
}

Para saques, use POST /v1/webhooks/resend-withdrawal-event com o body {"withdrawalIds": ["wd_uuid_1"]} — mesmos headers.

Privacidade dos Dados (LGPD)

Todos os payloads de webhook têm dados pessoais (PII) mascarados antes do envio:

Campo	Exemplo original	Mascarado
`customer.name`	`Joao Silva`	`Joao S.`
`customer.email`	`[email protected]`	`jo***@email.com`
`payer.name`	`Maria Oliveira`	`Maria O.`
`payer.document`	`12345678901`	`123.***.45`
`pixKey` (saque)	`[email protected]`	`jo***@email.com`
`destinationAccount.taxId` / `.name` / `.account` / `.pixKey`	dados do titular	mascarados (mesmo padrão acima)

Os campos não-pessoais da conta de destino (destinationAccount.bank, .branch, .accountType) são enviados sem máscara, por não conterem PII. Para acessar os dados completos, use GET /api/v1/cobranca/transactions/{id} ou GET /api/v1/cobranca/withdrawals/{id} com autenticação.

Visao Geral

Onboarding

Guias

Referencia

Webhooks

Webhooks

Como funciona

Anatomia de uma entrega

Validando a assinatura

Configurando um Endpoint de Webhook

Tipos de Evento

Eventos de Transação

TRANSACTION_CREATED

TRANSACTION_WAITING_PAYMENT

TRANSACTION_PAID

TRANSACTION_FAILED

TRANSACTION_EXPIRED

TRANSACTION_REFUNDED

Eventos de Saque

WITHDRAWAL_PROCESSING

WITHDRAWAL_PAID

WITHDRAWAL_REJECTED

WITHDRAWAL_FAILED

Eventos de Disputa

DISPUTE_CREATED

DISPUTE_RESOLVED

DISPUTE_REJECTED

MED_DISPUTE_CREATED

MED_DISPUTE_REFUND_COMPLETED

Comportamento de Retry

Reenviando Eventos Manualmente

Privacidade dos Dados (LGPD)

​Webhooks

​Como funciona

​Anatomia de uma entrega

​Validando a assinatura

​Configurando um Endpoint de Webhook

​Tipos de Evento

​Eventos de Transação

​TRANSACTION_CREATED

​TRANSACTION_WAITING_PAYMENT

​TRANSACTION_PAID

​TRANSACTION_FAILED

​TRANSACTION_EXPIRED

​TRANSACTION_REFUNDED

​Eventos de Saque

​WITHDRAWAL_PROCESSING

​WITHDRAWAL_PAID

​WITHDRAWAL_REJECTED

​WITHDRAWAL_FAILED

​Eventos de Disputa

​DISPUTE_CREATED

​DISPUTE_RESOLVED

​DISPUTE_REJECTED

​MED_DISPUTE_CREATED

​MED_DISPUTE_REFUND_COMPLETED

​Comportamento de Retry

​Reenviando Eventos Manualmente

​Privacidade dos Dados (LGPD)

Webhooks

Como funciona

Anatomia de uma entrega

Validando a assinatura

Configurando um Endpoint de Webhook

Tipos de Evento

Eventos de Transação

TRANSACTION_CREATED

TRANSACTION_WAITING_PAYMENT

TRANSACTION_PAID

TRANSACTION_FAILED

TRANSACTION_EXPIRED

TRANSACTION_REFUNDED

Eventos de Saque

WITHDRAWAL_PROCESSING

WITHDRAWAL_PAID

WITHDRAWAL_REJECTED

WITHDRAWAL_FAILED

Eventos de Disputa

DISPUTE_CREATED

DISPUTE_RESOLVED

DISPUTE_REJECTED

MED_DISPUTE_CREATED

MED_DISPUTE_REFUND_COMPLETED

Comportamento de Retry

Reenviando Eventos Manualmente

Privacidade dos Dados (LGPD)