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

# Webhooks

> O que a Lojou envia pra sua URL configurada, e quando.

Depois de registrar um webhook (`POST /v1/webhooks`), a Lojou faz um `POST` com um payload em JSON pra sua URL sempre que um dos eventos configurados acontece. Isso te evita ter que ficar consultando `GET /v1/orders/{id}` pra saber se um pedido mudou de status.

## Eventos disponíveis

| Evento            | Quando dispara                                                                                                                                                           |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `order_approved`  | O pagamento de um pedido foi confirmado.                                                                                                                                 |
| `order_cancelled` | Uma tentativa de pagamento falhou ou foi cancelada.                                                                                                                      |
| `order_refund`    | Aparece como opção ao criar um webhook pelo painel, mas **hoje nenhum evento real dispara isso** — nenhum reembolso aciona esse webhook ainda. Não conte com ele chegar. |

Escolha os eventos no campo `events` ao criar o webhook (`POST /v1/webhooks`).

## Escopo por produto

Um webhook pode ser filtrado pra um produto específico (defina `product_details` na criação) ou disparar pra **qualquer** produto da loja (deixe `product_details` de fora). Se você tiver mais de um webhook cadastrado pra mesma URL, a Lojou agrupa e manda só uma entrega por URL — não duplica.

## O payload

```json theme={null}
{
  "order_type": "order_approved",
  "order_number": "95428522",
  "status": "approved",
  "transaction_id": "T821671018874668",
  "payment_method": "card",
  "amount": 748.6,
  "currency": "MZN",
  "discount_amount": 0,
  "coupon_code": null,
  "original_amount": 748.6,
  "tracking": {
    "utm_source": "facebook",
    "utm_campaign": "lancamento",
    "utm_medium": null,
    "utm_content": null,
    "utm_term": null
  },
  "plan_subscriber": {
    "plan_name": null,
    "start_date": null,
    "end_date": null,
    "status": null,
    "plan_type": null,
    "plan_interval": null,
    "cancelled_at": null,
    "portal_url": "https://pay.lojou.app/order/95428522?transaction_id=T821671018874668"
  },
  "product": {
    "name": "Spy App",
    "price": "778.05",
    "pid": "QUyMp"
  },
  "customer": {
    "email": "maphate.tshepo77@gmail.com",
    "name": "Tshepo Joshua",
    "mobile_number": "+270637423882",
    "payment_number": null
  },
  "affiliate": [],
  "order_bump": [],
  "brand": "Lojou",
  "image": "https://api.lojou.app/assets/lojou-2.png"
}
```

`plan_subscriber` só vem preenchido de verdade pra produtos `recurring` (assinatura) — em produtos `one_time` os campos ficam `null`, exceto `portal_url`, que é sempre montado.

## Entrega — o que esperar

* **Sem assinatura/verificação criptográfica.** Hoje a Lojou não envia nenhum header tipo `X-Lojou-Signature` pra você validar a origem do payload. Trate a URL do seu endpoint como algo que só você conhece, e valide o conteúdo (ex: confirme o `order_number` chamando `GET /v1/orders/{id}`) antes de agir sobre ele em operações sensíveis.
* **Sem retry automático.** É uma única tentativa de `POST`, com timeout de 10s — se o seu endpoint estiver fora do ar ou demorar demais, essa entrega específica se perde (fica só registrado como falha no relatório do webhook, `GET /v1/webhooks/{id}` mostra o resumo). Se você precisa de garantia de entrega, use os webhooks como um aviso "algo mudou" e confirme com uma chamada `GET /v1/orders/{id}` depois.
* **Responda rápido, com `2xx`.** Qualquer coisa fora da faixa `2xx` conta como falha no relatório do webhook (mesmo que você já tenha processado o evento).

## Depurando

`GET /v1/webhooks/{id}` devolve um resumo (`summary`) com o horário e status da última entrega. Pra ver o payload exato que foi enviado numa tentativa específica e a resposta que seu endpoint devolveu, isso ainda só está disponível no painel da Lojou (Configurações → Webhooks → Relatórios) — não exposto pela API pública ainda.