Aviso de transação (transaction.created / transaction.paid / transaction.canceled)

Como funcionam os avisos

Cadastre a URL em POST /v2/webhooks escolhendo os eventos. A SwitchPay faz um POST com JSON nessa URL sempre que o evento acontecer.

Eventos

Tipo	Quando dispara
`transaction.created`	Transação criada (confirm da intenção)
`transaction.paid`	Pagamento confirmado
`transaction.canceled`	Cancelada, recusada, expirada ou com chargeback

O corpo é { id, type, createdAt, data: { transaction } }; transaction tem o mesmo formato de GET /v2/transactions/{id}. Campo novo no evento é adição (não muda a versão); mudança que quebra vira tipo de evento novo.

Cabeçalhos

Cabeçalho	Conteúdo
`X-Swp-Event-Id`	Id único do evento (use pra descartar repetido)
`X-Swp-Event`	Tipo do evento
`X-Swp-Timestamp`	Unix time (segundos) do envio
`X-Swp-Signature`	`v1=<hex>` — HMAC-SHA256 com o seu `secret` sobre `"{timestamp}.{corpo bruto}"`

Como validar

Monte a string "{X-Swp-Timestamp}.{corpo exatamente como recebido}" (bytes crus, antes de qualquer parse).
Calcule HMAC-SHA256 com o secret que veio no cadastro; saída em hexadecimal minúsculo.
Compare com o v1= do cabeçalho (comparação em tempo constante).
Rejeite se o timestamp tiver mais de 5 minutos.

Entrega e repetição

Responda 2xx em até 10 s. Sem 2xx, a SwitchPay tenta de novo com espera crescente (1 min, 5 min, 30 min, 2 h, 12 h — 5 tentativas em ~24 h). O mesmo evento pode chegar mais de uma vez: use X-Swp-Event-Id pra ignorar repetido. Em breve você vai poder reenviar um aviso pelo painel. (No sandbox, por enquanto: uma tentativa só, sem repetição.)

Request Body

idstring

Id único do evento (evt_…); igual ao cabeçalho X-Swp-Event-Id

typeEventType

Value in"transaction.created" | "transaction.paid" | "transaction.canceled"

createdAtstring

Quando o fato aconteceu

Formatdate-time

dataobject