> ## Documentation Index
> Fetch the complete documentation index at: https://developer.noodle.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações em tempo real sobre eventos importantes através de webhooks.

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

<Card title="Como configurar sua URL de Webhook" icon="paper-plane">
  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](mailto:api@noodle.cx)**.
</Card>

## 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.

<Tabs>
  <Tab title="qr_code_received">
    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

    ```json theme={null}
    {
        "webhook_type": "qr_code_received",
        "event_date": "2025-08-13T18:30:00Z",
        "data": {
            "pix_id": "E12345678202508131830sABCdeFG1",
            "amount": 150.75
        }
    }
    ```
  </Tab>

  <Tab title="split_created">
    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

    ```json theme={null}
    {
        "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
        }
    }
    ```
  </Tab>

  <Tab title="split_processed">
    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

    ```json theme={null}
    {
        "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
        }
    }
    ```
  </Tab>

  <Tab title="split_payment">
    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

    ```json theme={null}
    {
        "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
        }
    }
    ```
  </Tab>
</Tabs>

***

## Segurança e Verificação

<Note>
  É 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.
</Note>

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:**

1. Extraia o JWT do header `Authorization`.
2. Use a **chave pública** fornecida pela equipe da Noodle durante o seu processo de onboarding para verificar a assinatura do token.
3. 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**](https://developer.noodle.cx/authentication).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.