> ## Documentation Index
> Fetch the complete documentation index at: https://cryptouse-d1f5ba06.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receba notificações em tempo real sobre eventos importantes nas suas ordens

# Webhooks

Os webhooks da CryptoUse permitem que sua aplicação receba notificações automáticas sempre que determinados eventos ocorrem nas ordens. Isso elimina a necessidade de consultas constantes à API para verificar o status.

## Recursos principais

* **Notificações em tempo real**: Saiba imediatamente quando uma ordem for paga.
* **Automatização de processos**: Atualize o status dos seus pedidos, estoques ou serviços automaticamente.
* **Facilidade de integração**: Configure endpoints personalizados em poucos minutos.

## Eventos disponíveis

| Evento                    | Descrição                        |
| ------------------------- | -------------------------------- |
| `PIX:ORDER_SUCCESS`       | Ordem PIX paga com sucesso       |
| `ONCHAIN:ORDER_SUCCESS`   | Ordem ONCHAIN paga com sucesso   |
| `LIGHTNING:ORDER_SUCCESS` | Ordem LIGHTNING paga com sucesso |
| `PAYMENT_SUCCESSFUL`      | Ordem BINANCE paga com sucesso   |

## Como cadastrar um Webhook

Você pode cadastrar facilmente um webhook através do painel da CryptoUse. Siga o passo a passo abaixo para receber notificações em tempo real sempre que eventos importantes ocorrerem.

### Passo a passo

Na seção de perfil do usuário, procure por API/Webhooks.

<img src="https://mintcdn.com/cryptouse-d1f5ba06/1uno17SLpzDE3OTl/images/webhook-profile-section.png?fit=max&auto=format&n=1uno17SLpzDE3OTl&q=85&s=48a5d08d0a22d91c23c1f35563b949c5" alt="Formulário de cadastro de webhook" width="1174" height="209" data-path="images/webhook-profile-section.png" />

No canto superior direito, clique em "Adicionar webhook".

<img src="https://mintcdn.com/cryptouse-d1f5ba06/1uno17SLpzDE3OTl/images/add-webhook.png?fit=max&auto=format&n=1uno17SLpzDE3OTl&q=85&s=2f4d432cdef0f08de136bd7fdd502b12" alt="Formulário de cadastro de webhook" width="1452" height="174" data-path="images/add-webhook.png" />

Preencha as informações necessárias para criar seu webhook.

<img src="https://mintcdn.com/cryptouse-d1f5ba06/1uno17SLpzDE3OTl/images/pix-webhook.png?fit=max&auto=format&n=1uno17SLpzDE3OTl&q=85&s=767dce8a1ff1fc27d9c140469cff0684" alt="Formulário de cadastro de webhook" width="1503" height="895" data-path="images/pix-webhook.png" />

### 📝 Preenchendo o formulário

#### 🔹 **Nome**

* Descrição livre para você identificar o webhook.
* Exemplo: `Webhook de pedidos pagos`.

#### 🔹 **Evento**

* Selecione o evento que deseja escutar.
* Para receber notificações quando uma ordem for paga, escolha um evento.
* Exemplo: `PIX:ORDER_SUCCESS`.

#### 🔹 **URL**

* Endereço (endpoint) da sua aplicação que irá receber as notificações.
* Deve estar acessível publicamente e aceitar requisições POST no formato JSON.

Exemplo:\
`https://meusite.com/api/webhooks/order-success`

### 🔐 **Cabeçalhos HTTP (Opcional)**

Aqui você pode adicionar autenticações ou configurações específicas da sua API.

#### Cabeçalhos recomendados:

| Cabeçalho               | Valor                  | Descrição                                          |
| ----------------------- | ---------------------- | -------------------------------------------------- |
| `Accept`                | `application/json`     | Define que a requisição aceita JSON                |
| `Content-Type`          | `application/json`     | Formato da requisição                              |
| `X-Cryptouse-Signature` | Gerado automaticamente | Assinatura HMAC para validação da origem           |
| `Authorization`         | Seu token, opcional    | Use caso seu endpoint exija autenticação adicional |

### 🚀 Após configurar

1. Clique em **Salvar**.
2. Seu webhook estará ativo e passará a receber notificações sempre que o evento selecionado ocorrer.

## Ciclo de vida de um Webhook

1. **Cadastro**: Você informa a URL do seu endpoint na plataforma.
2. **Evento**: Quando o evento ocorre (ex.: pagamento confirmado), a CryptoUse envia uma requisição HTTP POST para a URL cadastrada.
3. **Processamento**: Sua aplicação recebe os dados do evento e executa as ações desejadas.
4. **Confirmação**: Seu servidor deve responder com status HTTP `200 OK` para confirmar o recebimento. Caso contrário, novas tentativas de entrega serão feitas.

## 🔗 Exemplo de Payload recebido

### PIX Order Success

```json theme={null}
{
  "universalUrl": "00020126840014br.gov.bcb.pix2562qrcode.transfeera....",
  "createdAt": "2025-06-03T13:52:34.048Z",
  "value": "500",
  "event": "PIX:ORDER_SUCCESS"
}
```

### Onchain Order Success

```json theme={null}
{
  "createdAt": "2025-08-01T19:45:18.264Z",
  "value": "0.10",
  "event": "ONCHAIN:ORDER_SUCCESS",
  "walletAddress": "0x6c...",
  "network": "bsc",
  "asset": "USDT",
  "cryptoValue": 0.019,
  "paymentLinkId": "fd71ff5d-ac4f-..."
}
```