Webhooks
Cada mudança de estado, assinada, no backend do parceiro.
POST/v1/webhook-endpoints
curl -X POST $OXUS_API/v1/webhook-endpoints \
-H "Authorization: Bearer $OXUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.parceiro.com.br/webhooks/oxus",
"events": ["transfer.updated", "transfer.completed", "transfer.failed", "transfer.refunded", "kyc.audit_requested"]
}'A resposta traz o secret (whsec_…) uma única vez. Guarde-o no seu cofre de segredos.
Eventos
| Evento | Quando |
|---|---|
customer.created, customer.updated | Cadastro e mudança de status do cliente |
kyc.attestation.accepted | Atestação validada |
kyc.audit_requested | Nova solicitação de auditoria |
kyc.audit_access_expired | Fim do acesso de uma auditoria |
receiver.created, receiver.validated | Conta de destino cadastrada e validada |
transfer.created | Transferência criada, com as instruções de pagamento |
transfer.updated | Mudança de etapa ou status |
transfer.completed | Valor entregue |
transfer.failed | Entrega recusada no destino; o reembolso segue sozinho |
transfer.refunded | Valor devolvido ao cliente, por reembolso automático ou pedido do parceiro |
Verificação da assinatura
Cada entrega traz svix-id, svix-timestamp e svix-signature, no padrão Standard Webhooks.
import { Webhook } from 'svix'
const webhookVerifier = new Webhook(process.env.OXUS_WEBHOOK_SECRET!)
export async function handleOxusWebhook(request: Request): Promise<Response> {
const rawBody = await request.text()
// Throws when the signature or the timestamp is invalid.
const event = webhookVerifier.verify(rawBody, {
'svix-id': request.headers.get('svix-id')!,
'svix-timestamp': request.headers.get('svix-timestamp')!,
'svix-signature': request.headers.get('svix-signature')!,
})
await enqueueForProcessing(event) // answer fast, process asynchronously
return new Response(null, { status: 204 })
}Entrega
- Pelo menos uma vez. Responda
2xxem até 15 segundos. Qualquer outra resposta gera nova tentativa. - Retentativas: imediata, 5 s, 5 min, 30 min, 2 h, 5 h, 10 h e 10 h.
- Duplicatas. Uma retentativa repete o
iddo evento. Ignore IDs já processados. - Ordem. Eventos podem chegar fora de ordem. Use
data.updatedAtou consulte o recurso.
Teste
POST/v1/webhook-endpoints/{endpointId}/testEnvia um transfer.updated assinado de verdade para o endpoint. Para inspecionar sem código, registre uma URL do webhook.site.