Segurança e Exemplos

---

Autenticação

Cada requisição de webhook inclui o header de autenticação configurado na assinatura. Por padrão, o header utilizado é Authorization:

POST https://seu-servidor.com/webhook
Authorization: seu-token-secreto
Content-Type: application/json

O nome do header é configurável. Embora o padrão seja Authorization, é possível utilizar qualquer header customizado (ex: X-Webhook-Secret, X-Api-Key). O nome e valor são definidos na assinatura do webhook.

Valide o header em cada requisição recebida e rejeite com 401 caso o token seja inválido.

Recomendações

• HTTPS obrigatório — configure seus endpoints exclusivamente com HTTPS

• Valide o header — sempre verifique o token de autenticação antes de processar o payload

• Timeout curto — responda rapidamente (< 30s). Processe o payload de forma assíncrona se necessário

• Whitelist de IPs — se possível, restrinja o acesso ao IP de origem do GTPayroll (solicite à equipe de integração)

---

Exemplos de implementação

Recebendo webhooks (Node.js / Express)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  const token = req.headers['authorization'];

  if (token !== process.env.WEBHOOK_SECRET) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  const payload = req.body;
  console.log('Webhook received:', JSON.stringify(payload));

  // Processe o evento de forma assíncrona
  processWebhookAsync(payload);

  // Responda imediatamente com 200
  res.status(200).json({ received: true });
});

app.listen(3000);

Recebendo webhooks (Python / Flask)

from flask import Flask, request, jsonify
import os

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    token = request.headers.get('Authorization')

    if token != os.environ.get('WEBHOOK_SECRET'):
        return jsonify({'error': 'Unauthorized'}), 401

    payload = request.get_json()
    print(f'Webhook received: {payload}')

    # Processe o evento de forma assíncrona
    process_webhook_async(payload)

    return jsonify({'received': True}), 200

Recebendo webhooks (Java / Spring Boot)

@RestController
@RequestMapping("/webhook")
public class WebhookController {

    @Value("${webhook.secret}")
    private String webhookSecret;

    @PostMapping
    public ResponseEntity<Map<String, Boolean>> handleWebhook(
            @RequestHeader("Authorization") String token,
            @RequestBody Map<String, Object> payload) {

        if (!webhookSecret.equals(token)) {
            return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
        }

        log.info("Webhook received: {}", payload);

        // Processe de forma assíncrona
        processWebhookAsync(payload);

        return ResponseEntity.ok(Map.of("received", true));
    }
}

---

Troubleshooting

Problema	Causa provável	Solução
Webhook não recebido	Assinatura inativa ou URL incorreta	Verifique a configuração no painel administrativo
Erro 401/403	Token de autenticação incorreto	Confirme o header e valor configurados na assinatura
Evento cancelado sem retry	Seu endpoint retornou 4xx	Corrija o endpoint para retornar 2xx e solicite reenvio
Eventos duplicados	Retry após timeout	Implemente idempotência no seu endpoint
Timeout na entrega	Endpoint lento (> 60s)	Processe o payload de forma assíncrona e responda rapidamente
Evento não chega após retry	Limite de 5 tentativas atingido	Solicite reenvio manual à equipe de suporte

Em caso de problemas persistentes, entre em contato com a equipe de integração informando o originatorId e o período dos eventos afetados.

---

Checklist de integração

• Endpoint HTTPS configurado e acessível publicamente

• Validação do header de autenticação implementada

• Resposta 200 retornada rapidamente (< 30s)

• Processamento assíncrono do payload implementado

• Idempotência implementada para evitar duplicatas

• Tratamento de cada tipo de evento necessário

• Monitoramento e alertas configurados para falhas no endpoint

• Teste end-to-end realizado com a equipe de integração