Webhooks - Mint Starter Kit

Nossos webhooks enviam uma requisição POST para a URL que você configurar sempre que um evento específico ocorre. O corpo da requisição contém um objeto JSON com todos os detalhes do evento.

Configuração do Endpoint

Como configurar sua URL de Webhook

A URL para a qual enviaremos os eventos de webhook é configurada pela equipe da Noodle durante o processo de onboarding da sua integração.Para cadastrar uma nova URL ou solicitar alterações, por favor, entre em contato através do e-mail api@noodle.cx.

O Objeto `WebhookEvent`

Todos os eventos de webhook são enviados no mesmo formato de envelope. O campo webhook_type indica qual evento ocorreu, e o objeto data contém a carga útil (payload) específica para aquele evento.

Atributo	Tipo	Descrição
`webhook_type`	`string`	O tipo do evento. Veja a lista completa de tipos abaixo.
`event_date`	`datetime`	A data e hora em UTC (`YYYY-MM-DDTHH:MM:SSZ`) em que o evento foi gerado.
`data`	`object`	Um objeto contendo os dados específicos do evento. A estrutura varia com o `webhook_type`.

Tipos de Eventos e Payloads

A seguir, detalhamos a estrutura do objeto data para cada tipo de evento.

qr_code_received
split_created
split_processed
split_payment

Disparado quando um pagamento via QR Code é recebido com sucesso.

Atributos

Atributo	Tipo	Descrição
`pix_id`	`string`	O ID único da transação PIX.
`amount`	`float`	O valor total do pagamento recebido.

Exemplo de Payload

{
    "webhook_type": "qr_code_received",
    "event_date": "2025-08-13T18:30:00Z",
    "data": {
        "pix_id": "E12345678202508131830sABCdeFG1",
        "amount": 150.75
    }
}

Disparado quando uma nova divisão de pagamento (split) é criada.

Atributos

Atributo	Tipo	Descrição
`split_id`	`string`	O ID único da divisão de pagamento criada.
`pix_qr_code_id`	`string`	ID do QR Code Pix associado. (Opcional)
`pix_qr_code_payload`	`string`	Payload do QR Code Pix associado. (Opcional)
`total_amount`	`float`	O valor total a ser dividido.
`pending_payments`	`integer`	O número total de pagamentos que compõem a divisão.
`withhold_payments`	`integer`	O número de pagamentos que estão retidos.

Exemplo de Payload

{
    "webhook_type": "split_created",
    "event_date": "2025-08-13T18:31:00Z",
    "data": {
        "split_id": "63222dccb09dcd7f5c48304b",
        "pix_qr_code_id": "qrcd_12345",
        "pix_qr_code_payload": "00020126...",
        "total_amount": 1000.00,
        "pending_payments": 4,
        "withhold_payments": 1
    }
}

Disparado após o processamento de uma divisão, informando o status geral.

Atributos

Atributo	Tipo	Descrição
`split_id`	`string`	O ID único da divisão de pagamento.
`paid_amount`	`float`	O valor total que já foi pago.
`pending_amount`	`float`	O valor total que ainda está pendente.
`pending_payments`	`integer`	O número de pagamentos ainda pendentes.
`paid_payments`	`integer`	O número de pagamentos que já foram concluídos.

Exemplo de Payload

{
    "webhook_type": "split_processed",
    "event_date": "2025-08-13T18:32:00Z",
    "data": {
        "split_id": "63222dccb09dcd7f5c48304b",
        "paid_amount": 500.00,
        "pending_amount": 500.00,
        "pending_payments": 2,
        "paid_payments": 2
    }
}

Disparado para cada pagamento individual dentro de uma divisão, informando seu status.

Atributos

Atributo	Tipo	Descrição
`payment_id`	`string`	O ID único do pagamento individual.
`amount`	`float`	O valor deste pagamento específico.
`status`	`string`	O status atual do pagamento (`PENDING`, `PAID`, `WITHHOLD`, `ERROR`, `REVERSAL`).
`transaction_id`	`string`	O ID da transação, se o pagamento foi bem-sucedido. (Opcional)
`error_reason`	`string`	A razão da falha, caso o status seja `failed`. (Opcional)

Exemplo de Payload

{
    "webhook_type": "split_payment",
    "event_date": "2025-08-13T18:33:00Z",
    "data": {
        "payment_id": "pay_K1L0M9N8P7",
        "amount": 250.00,
        "status": "PAID",
        "transaction_id": "txn_Q6R5S4T3U2",
        "error_reason": null
    }
}

Segurança e Verificação

É crucial que você valide a assinatura de cada webhook recebido para garantir que a requisição veio da nossa API e não foi adulterada.

A autenticação dos webhooks segue o mesmo padrão de autenticação JWT (JSON Web Token) descrito na nossa página principal de autenticação. Para cada requisição de webhook, enviaremos um header Authorization com um token Bearer: Authorization: Bearer <seu_jwt_aqui> Para validar a requisição:

Extraia o JWT do header Authorization.
Use a chave pública fornecida pela equipe da Noodle durante o seu processo de onboarding para verificar a assinatura do token.
Se a assinatura for válida, processe o evento. Caso contrário, descarte a requisição.

Para mais detalhes sobre a estrutura do token e as bibliotecas recomendadas para validação, por favor, consulte a nossa documentação de autenticação principal.

​Configuração do Endpoint

Como configurar sua URL de Webhook

​O Objeto WebhookEvent

​Tipos de Eventos e Payloads

​Atributos

​Exemplo de Payload

​Atributos

​Exemplo de Payload

​Atributos

​Exemplo de Payload

​Atributos

​Exemplo de Payload

​Segurança e Verificação

Configuração do Endpoint

O Objeto `WebhookEvent`

Tipos de Eventos e Payloads

Atributos

Exemplo de Payload

Atributos

Exemplo de Payload

Atributos

Exemplo de Payload

Atributos

Exemplo de Payload

Segurança e Verificação