Eventos de Webhook

Introdução

Os webhooks são notificações enviadas para a URL especificada no campo postbackUrl quando ocorrem mudanças no status de uma transação. Cada evento é enviado como uma requisição POST com um payload JSON contendo informações sobre a transação.

Estrutura do Payload do webhook

Todos os eventos seguem a seguinte estrutura base:

{
    "id": "F92XRTVSGB2B",
    "type": "transaction",
    "objectId": "28a65292-6c74-4368-924d-f52a653706be",
    "data": {
        "id": "28a65292-6c74-4368-924d-f52a653706be",
        "amount": 10000,
        "refundedAmount": null,
        "description": "Transação criada via API",
        "companyId": "6b366424-d046-41c6-8976-22a516f7dfb8",
        "installments": 1,
        "paymentMethod": "PIX",
        "status": "paid",
        "postbackUrl": "https://webhook.site/0d7aef0c-ad93-4a7c-8514-30d9b2896750",
        "metadata": null,
        "createdAt": "2025-04-03T15:59:43-03:00",
        "updatedAt": "2025-04-03T15:59:43-03:00",
        "paidAt": "2025-04-03T15:59:43.56-03:00",
        "ip": null,
        "customer": {
            "id": "96155cff-4224-46fd-af28-ba58d6b06301",
            "name": "TESTE PIX",
            "email": "[email protected]",
            "phone": "11999999999",
            "createdAt": "2025-04-03T15:59:43.131002",
            "document": "01234567890"
        },
        "card": null,
        "boleto": null,
        "pix": {
            "qrcode": "https://digital.mundipagg.com/pix/",
            "expirationDate": "2025-04-03T16:19:43-03:00",
            "end2EndId": "E12345678202009091221abcdef12345",
            "receiptUrl": null
        },
        "shipping": {
            "neighborhood": "centro",
            "zipCode": "49070083",
            "city": "Aracaju",
            "complement": "",
            "streetNumber": "11",
            "street": "Rua Bolívia",
            "state": "SE"
        },
        "refusedReason": null,
        "items": [
            {
                "title": "Camisa G",
                "unitPrice": 10000,
                "quantity": 1,
                "externalRef": "yshZlkj4eFo2imq7TOH158g1mp0akci8"
            }
        ],
        "splits": [
            {
                "recipientId": "21cb8a8b-35e4-44bf-aa72-130a1154b42a",
                "percentage": 100,
                "netAmount": 9900
            }
        ],
        "fee": {
            "fixedAmount": 1,
            "spreadPercentage": 0.6,
            "estimatedFee": 100,
            "netAmount": 9900
        }
    }
}

Status Possíveis

Status	Descrição	Ação Recomendada
`waiting_payment`	Transação criada, aguardando pagamento	Aguardar pagamento do cliente
`paid`	Transação paga com sucesso	Confirmar entrega do produto/serviço
`refused`	Transação recusada	Verificar motivo da recusa e notificar cliente
`canceled`	Transação cancelada	Atualizar sistema e notificar cliente
`refunded`	Transação estornada	Atualizar sistema e verificar motivo do estorno
`chargedback`	Transação com chargeback	Iniciar processo de contestação
`failed`	Transação falhou	Verificar motivo da falha e tentar novamente
`expired`	Transação expirou	Oferecer nova opção de pagamento ao cliente
`in_analisys`	Transação em análise	Aguardar resultado da análise
`in_protest`	Transação em protesto	Iniciar processo de contestação

Boas Práticas

Resposta Rápida: Responda ao webhook com status 200 o mais rápido possível (dentro de 5 segundos)
Idempotência: Implemente sua lógica de forma idempotente para evitar processamento duplicado
Retry: Em caso de falha, tentaremos reenviar o webhook até 3 vezes
Logging: Mantenha logs de todos os webhooks recebidos para debugging