Ir para o conteúdo
Sharkpay

Documentação da API

Integre pagamentos, saques e webhooks ao seu sistema com uma API HTTP/JSON aberta e documentada.

API 2026-10-14

Webhooks

O SharkPay avisa o seu servidor quando uma cobrança ou saque muda de estado. Cada evento é um POST JSON assinado com HMAC-SHA256; verifique a assinatura antes de confiar no conteúdo.

Configurar

  1. Tenha um endereço https público (porta 443 ou 8443, sem usuário/senha na URL). URLs que resolvem para IP privado/reservado são recusadas.
  2. Chame PUT /api/webhook. Na primeira vez a resposta traz o segredo whsec_… — mostrado uma única vez.
  3. Guarde o segredo em variável de ambiente/cofre. Perdeu? POST /api/webhook/secret/rotate gera outro e invalida o anterior na hora.
  4. Teste com POST /api/webhook/test (envia um evento ping).
PUT /api/webhook
#!/usr/bin/env bash
# Configurar a URL do webhook
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
curl -sS --fail-with-body -X PUT "$SHARKPAY_BASE_URL/api/webhook" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "'"$WEBHOOK_URL"'"
}'
echo
POST /api/webhook/test
#!/usr/bin/env bash
# Enviar evento de teste
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
curl -sS --fail-with-body -X POST "$SHARKPAY_BASE_URL/api/webhook/test" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN"
echo

Eventos

typeQuandodata
invoice.paid Cobrança passou a PAID. invoice: reference, invoice_no, total, status
invoice.canceled Cobrança passou a CANCELED. invoice: …
invoice.refunded Cobrança passou a REFUNDED. invoice: …
order.paid Venda de produto confirmada (pagamento aprovado). order: reference, status, total, quantity, product{reference,name}, customer{name,email}, paid_at
order.canceled Venda de produto cancelada. order: …
order.refunded Venda reembolsada/estornada. order: …
pixout.paid Saque Pix concluído. withdraw: reference, amount, status
pixout.canceled Saque Pix cancelado (valor devolvido ao saldo). withdraw: …
ping Teste manual. message
Corpo do evento
{
  "id": "evt_abcdefghijklmnopqrstuvwx",
  "type": "invoice.paid",
  "created": 1760000000,
  "api_version": "2026-10-14",
  "data": {
    "invoice": { "reference": "INV-A1B2C3", "invoice_no": "PED-1042", "total": "190.00", "status": "PAID" }
  }
}

Cabeçalhos enviados

CabeçalhoConteúdo
SharkPay-Signature t=<unix>,v1=<hex> — HMAC-SHA256 de "t.corpo" com o segredo whsec_…
SharkPay-Event-Id Id do evento (igual ao campo id); use para deduplicar.
Content-Type application/json
User-Agent SharkPay-Webhooks/1.0

Verificar a assinatura

  1. Leia o corpo bruto (bytes) — não o JSON já reserializado.
  2. Extraia t e v1 do cabeçalho.
  3. Calcule HMAC_SHA256(segredo, t + "." + corpo) em hexadecimal.
  4. Compare em tempo constante com v1.
  5. Rejeite se |agora − t| > 300 s (anti-replay).
Receptor com verificação
#!/usr/bin/env bash
# Simula localmente uma entrega assinada para testar o SEU receptor (nenhuma chamada ao SharkPay).
set -euo pipefail
: "${SHARKPAY_WEBHOOK_SECRET:?}" "${RECEIVER_URL:?ex.: http://localhost:3000}"
BODY='{"id":"evt_local_1","type":"ping","created":'$(date +%s)',"api_version":"2026-10-14","data":{"message":"hello"}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$SHARKPAY_WEBHOOK_SECRET" -hex | sed 's/^.* //')
curl -sS -X POST "$RECEIVER_URL" -H "Content-Type: application/json" \
  -H "SharkPay-Signature: t=$T,v1=$SIG" -H "SharkPay-Event-Id: evt_local_1" -d "$BODY"
echo

Entrega e retentativas

  • Sucesso = resposta 2xx em até 10 s (conexão em 5 s). Redirecionamentos não são seguidos.
  • Qualquer outra coisa (4xx, 5xx, timeout) agenda nova tentativa, até 8 tentativas, com intervalos de 1, 5, 15, 60, 180, 360 e 720 minutos.
  • A entrega é pelo menos uma vez: o mesmo evento pode chegar repetido. Deduplique por id.
  • A ordem não é garantida. Em caso de dúvida, consulte a cobrança antes de agir.
  • Os eventos são gravados na mesma transação que a mudança de status (padrão outbox): se o status mudou, o evento existe.

Para diagnosticar, use GET /api/webhook/deliveries (últimas 25 entregas, com status HTTP, tentativas e próxima tentativa).

GET /api/webhook/deliveries
#!/usr/bin/env bash
# Ver entregas recentes
set -euo pipefail
: "${SHARKPAY_BASE_URL:?defina a URL base, ex.: https://pay.exemplo.com}"
: "${SHARKPAY_TOKEN:?obtenha o token com o exemplo "auth"}"
curl -sS --fail-with-body -X GET "$SHARKPAY_BASE_URL/api/webhook/deliveries" \
  -H "Authorization: Bearer $SHARKPAY_TOKEN"
echo

Boas práticas do receptor

  • Responda 200 rápido; processe em fila. Não faça trabalho pesado antes de responder.
  • Valide a assinatura antes de ler o corpo; responda 400 se inválida.
  • Seja idempotente: guarde os id já processados.
  • Não confie só no evento para ações críticas: confirme o estado atual pela API.
  • Exponha o receptor apenas por HTTPS e registre erros sem gravar o segredo.