Webhooks

Webhooks são a forma correta de saber o resultado de uma cobrança — nunca faça polling. O SDK verifica a assinatura e devolve um evento com event.type e event.payload.object.

Verifique a assinatura

Sempre verifique com o corpo cru (os bytes exatos que chegaram), antes de fazer parse do JSON.

from flask import request, abort
from selectwin import construct_event, SignatureVerificationError

@app.post("/webhooks/selectwin")
def selectwin_webhook():
    try:
        event = construct_event(
            request.get_data(),                              # bytes crus — não re-serialize
            request.headers.get("x-selectwin-signature"),    # header de assinatura
            os.environ["SELECTWIN_WEBHOOK_SECRET"],          # whsec_…
        )
    except SignatureVerificationError:
        abort(400)

    if event.type == "transaction.approved":
        tx = event.payload.object   # o recurso do evento
        # dê baixa no pedido

    return "", 200

Em clientes assíncronos, use sw.webhooks.construct_event(...) (mesma assinatura). construct_event levanta SignatureVerificationError quando o secret está ausente, o header falta, a assinatura não confere ou o corpo não é JSON válido.

O objeto do evento

SelectwinEvent expõe id, type, source, payload (com payload.object), correlation_id, account, created_at e updated_at. Também dá para acessar o dicionário cru por chave (event["type"], event.get(...)). Para o catálogo de tipos, o SDK exporta WEBHOOK_EVENT_TYPES, o tipo WebhookEventType e is_webhook_event_type.

Proteção contra replay (opcional)

Para rejeitar entregas antigas, passe o header com timestamp assinado (X-Selectwin-Signature-v1) e uma tolerância em segundos:

event = construct_event(
    request.get_data(),
    request.headers.get("x-selectwin-signature"),
    secret,
    signature_v1=request.headers.get("x-selectwin-signature-v1"),
    tolerance=300,  # rejeita entregas com mais de 5 min
)

Próximos passos

• Verificando assinaturas (HMAC) — o algoritmo em detalhe.
• Catálogo de eventos — todos os event.type.
• Tratamento de erros.