> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecorvex.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral dos webhooks

> Como funcionam os webhooks na Corvex, eventos disponíveis e onde ver exemplos de payload.

Quando um pedido muda de estado ou um carrinho é abandonado, a Corvex pode avisar o seu servidor com um **HTTP POST** em JSON. Você registra a URL e os eventos pela [API v1 de webhooks](/api/v1/webhooks).

<CardGroup cols={2}>
  <Card title="Exemplos de payload" icon="file-json" href="/webhooks-payloads">
    Corpos `corvex.order.*` e `corvex.cart.abandoned`, assinatura HMAC e boas práticas.
  </Card>

  <Card title="Gerenciar webhooks" icon="settings" href="/api/v1/webhooks">
    Criar, listar, editar URL, eventos, secret e ver logs de entrega.
  </Card>
</CardGroup>

## Fluxo

```mermaid theme={null}
sequenceDiagram
  participant Corvex
  participant Seu servidor
  Corvex->>Seu servidor: POST JSON (evento)
  Seu servidor-->>Corvex: 2xx em poucos segundos
```

1. Você cria o webhook com `POST /api/v1/webhooks` (URL HTTPS, lista de eventos, `secret` opcional).
2. Quando o evento ocorre na loja, a Corvex envia POST para a URL.
3. Seu endpoint responde **2xx** rapidamente; processe o pedido de forma assíncrona se precisar.
4. Falhas temporárias podem gerar **novas tentativas** — trate o mesmo `id` de forma idempotente.

## Eventos

| Configuração na API (`events[]`) | Campo `event` no POST    |
| -------------------------------- | ------------------------ |
| `ORDER_CREATED`                  | `corvex.order.created`   |
| `ORDER_PAID`                     | `corvex.order.paid`      |
| `ORDER_CANCELLED`                | `corvex.order.cancelled` |
| `ORDER_REFUNDED`                 | `corvex.order.refunded`  |
| `CART_ABANDONED`                 | `corvex.cart.abandoned`  |

`corvex.order.pending` é interno e **não** é enviado a endpoints de lojistas.

## O que vem no POST

Todo payload inclui um identificador do evento, o nome do evento e os dados do pedido ou do carrinho. Valores monetários vêm em **reais** (decimal), não em centavos.

Exemplo resumido de pedido pago:

```json theme={null}
{
  "id": "f7542077-5b0b-4b4a-9283-8cd16fc70b96",
  "event": "corvex.order.paid",
  "amount": 374.32,
  "status": "paid",
  "method": "pix",
  "client": {
    "name": "Ana Silva",
    "email": "ana.silva@example.com",
    "phone": "5511987654321"
  }
}
```

O exemplo completo e variações por evento estão em [Payload dos webhooks](/webhooks-payloads).

## Assinatura (recomendado)

Com `secret` configurado, valide o header `X-Webhook-Signature` (HMAC-SHA256 do body JSON). Detalhes e código em [Payload dos webhooks](/webhooks-payloads#autenticação-do-post).

## Requisitos da sua URL

* **HTTPS** público (sem localhost em produção).
* Resposta **2xx** em até alguns segundos.
* Trate campos opcionais e `null` com segurança.

<AccordionGroup>
  <Accordion title="Posso usar a mesma URL para vários eventos?" icon="link">
    Sim. Passe vários valores em `events` ao criar o webhook. Use o campo `event` do body para rotear no seu código.
  </Accordion>

  <Accordion title="Como testar sem pedido real?" icon="flask-conical">
    Use uma loja de homologação no painel, dispare um checkout de teste e confira os [logs do webhook](/api/v1/webhooks/\{webhookId}/logs) na API.
  </Accordion>

  <Accordion title="Webhook vs automação interna?" icon="workflow">
    Webhooks avisam **seu** sistema. [Automações](/automations) enviam e-mail, SMS e WhatsApp pela Corvex — contratos diferentes.
  </Accordion>
</AccordionGroup>