S2S Postback: Configuração Avançada de Afiliados com HMAC

Doğa comanda uma agência de performance marketing em Şişli, Istambul, e leva 38 restaurantes ao thMenu como afiliada. Ao migrar de relatórios manuais para postback S2S, seu ROI subiu 220 %, porque cada evento de comissão flui automaticamente para sua plataforma de atribuição.

Por que postback S2S

O postback server-to-server é uma ponte direta, sem navegador, entre seu servidor de tracking e o motor de comissões thMenu. Diferente do pixel, é imune a perda de cookies, bloqueadores e ITP da Apple. Doğa gera mais de 1.200 eventos mensais.

No thMenu Phase 3 cada evento — created, refunded, released — dispara um POST para a URL registrada. Payload assinado em HMAC-SHA256 no header X-thMenu-Signature.

Setup pelo dashboard

Três passos em Settings → Postback:

1. Cole o endpoint no campo Postback URL (HTTPS obrigatório). 2. Ative Enabled; o sistema gera um secret de 64 caracteres. 3. Copie o secret uma única vez — não aparece novamente.

Doğa armazena o secret como variável de ambiente Vercel THMENU_POSTBACK_SECRET. O endpoint valida a assinatura, escreve no Postgres e responde 401 quando inválida.

Payload e retries

O payload JSON inclui event_type, affiliate_id, commission_id, amount_cents, currency, timestamp e idempotency_key para impedir duplicidade.

Em caso de falha, o thMenu tenta 5 vezes com backoff exponencial (1m, 5m, 30m, 2h, 12h), depois marca "dead" e alerta o super-admin.

FAQ

Como verificar a assinatura? Calcule HMAC-SHA256 do body cru com seu secret e compare em tempo constante com o header.

E se eu perder o secret? Desative e reative o postback — um novo é gerado imediatamente.

Quais tiers? Todos os afiliados ativos, sem restrição de nível.

Achou útil? Compartilhe.