Webhooks - Lojou Docs

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

{
  "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": "[email protected]",
    "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.

​Eventos disponíveis

​Escopo por produto

​O payload

​Entrega — o que esperar

​Depurando

Eventos disponíveis

Escopo por produto

O payload

Entrega — o que esperar

Depurando