Webhook próprio

Com um webhook próprio, a loja envia um POST para o endereço que você escolher sempre que algo acontece. É o caminho para avisar um CRM, um ERP, um bot ou qualquer automação.

Cadastrar#

1. Abra Webhooks#

   Em Configuração, encontre a seção Webhooks e clique em Criar.

2. Escolha Webhook próprio#

   Informe a URL do seu sistema e dê um nome ao webhook. Em produção a URL precisa ser https.

3. Marque os eventos#

   Evento	Quando dispara	Quem pode assinar
   order_paid	Pagamento confirmado	Quem pode ver vendas
   chat_created	Chat aberto	Quem tem acesso total
   chat_message	Mensagem do comprador ou da equipe	Quem tem acesso total
   feedback_create	Avaliação recebida	Quem pode ver avaliações

   Os eventos de chat entregam a conversa inteira, inclusive de chats privados. Por isso, só quem tem acesso total pode assinar.

4. Guarde o Secret#

   Ao salvar, o painel mostra o Secret uma única vez. Ele serve para o seu sistema confirmar que o evento veio mesmo da loja.

5. Teste#

   Use o botão de teste e veja o resultado no histórico de entregas.

O que chega#

Exemplo do evento order_paid:

{
  "event_name": "order_paid",
  "order": {
    "id": "6f2c1a9e-6c1f-4f0e-9a51-3d3f4f2c7b10",
    "number": 1001,
    "status": "paid",
    "total": 15.5,
    "currency": "BRL",
    "method": "pix",
    "gateway": "promissepay",
    "paid_at": "2026-10-31T15:04:05.000Z",
    "coupon": null,
    "customer": { "name": "Ana Lima", "email": "ana@exemplo.com", "phone": "11999998888" },
    "utm": {}
  },
  "items": [
    { "id": "b1c7e3f2-2f6f-4d3f-8b43-0d1f0e7a9c21", "product_id": "0f0e5b0c-2b7c-4a6e-9c0d-7a5a4a3b2c1d", "variant_id": null, "name": "Curso", "variant": null, "quantity": 1, "unit_price": 15.5 }
  ]
}

Os valores chegam em reais, com casas decimais.

Validar e tratar#

Toda entrega traz a assinatura no cabeçalho x-webhook-signature. Confira antes de confiar no conteúdo. A página de desenvolvedores tem o exemplo pronto em Node, os outros eventos e as regras de nova tentativa.