Webhooks de parceiros

Registe um endpoint HTTPS para receber eventos de pagamento. A chave deve ter webhooks:write para criar/desactivar endpoints e repetir entregas; webhooks:read para consultar endpoints e histórico. Estas rotas ficam vinculadas à conta e ao ambiente da chave.

Criar endpoint de webhook

POST/v1/webhook-endpoints

Envie URL HTTPS sem credenciais, query string nem fragmento, os tipos de evento e um Idempotency-Key. O segredo whsec_… aparece apenas na resposta de criação; guarde-o imediatamente. A repetição idempotente não o devolve outra vez.

curl -i -X POST \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: webhook-endpoint-setup-0001' \
  --data '{"url":"https://merchant.example.com/payment-events","events":["payment.succeeded","payment.failed"]}' \
  "https://api-pay.edutecka.com/v1/webhook-endpoints"

Eventos suportados: payment.created, payment.updated, payment.succeeded, payment.failed e payment.cancelled. Payload inclui ID estável do evento e dados do pagamento sem telefone nem resposta bruta do provider. Um evento pode ser entregue mais de uma vez; deduplique sempre por Payment-Event-Id.

Cada pedido inclui Payment-Event-Id, Payment-Event-Type, Payment-Delivery-Id, Payment-Delivery-Attempt e Payment-Signature: t=<unix>,v1=<hex>. Verifique a assinatura sobre os bytes originais: HMAC-SHA256 com a chave secreta, usando timestamp + "." + corpo JSON exacto; compare em tempo constante e rejeite timestamps antigos antes de processar.

Consultar endpoints e entregas

GET/v1/webhook-endpoints

POST/v1/webhook-endpoints/{id}/disable

GET/v1/webhook-deliveries?limit=50

GET/v1/webhook-deliveries/{id}

Repetir uma entrega

POST/v1/webhook-deliveries/{id}/retry

Estado e política de entrega

A API guarda status, tentativas, status HTTP, duração e códigos de falha, sem guardar corpo de resposta. HTTP 2xx conclui a entrega; 408, 425, 429, 5xx e falhas de transporte são repetidos com espera crescente, até 12 tentativas. Outros 4xx e redirects terminam a entrega. A tentativa manual só é aceite para entrega falhada com endpoint activo. Uma chamada que já estava em curso pode terminar enquanto o endpoint é desactivado.

Disponibilidade: o código destas rotas está pronto, mas o runtime activo ainda precisa das migrations 0014/0015, da variável independente PLATFORM_WEBHOOK_ENCRYPTION_KEY e do deploy correspondente. Suporte ao evento payment.succeeded não substitui callback autenticado nem reconciliação financeira oficial.