Anexo B — Contrato de Webhook da PIED

Informação extraída em 16/06/2026 da documentação de webhooks da PIED. Resumo simplificado, só com o necessário para definir o escopo.

Eventos disponíveis

Evento	Quando dispara
budget.created / budget.updated	Orçamento criado / atualizado
order.created / order.updated	Pedido criado / atualizado

Empresas (clientes) também disparam evento segundo a doc, mas sem nome publicado — a confirmar. Não há webhook de produto.

Request (PIED → nós)

A PIED faz um POST HTTPS para a URL configurada. O data é completo (mesmo formato do pedido no Anexo A — não exige uma segunda consulta na maioria dos casos).

POST /webhook/pied
Content-Type: application/json

{
  "event": "order.created",
  "data": {
    "id": "6f3a9c12", "code": "200000123", "type": "order", "kind": "Kit Personalizado",
    "totalPower": 5.5, "dealStatus": "Novo", "finalValue": 23750,
    "company": { "cnpj": "12.345.678/0001-09", "companyName": "Solar Sul Ltda",
                 "mainContact": { "email": "joao@solarsul.com", "cellphone": "5642999990000" },
                 "address": { "CEP": "84010-000", "state": "PR", "city": "Ponta Grossa" } },
    "products": [ { "productCode": "MOD-550", "quantity": 10, "singlePrice": 780, "center": { "code": "CD001" } } ],
    "payment": { "type": "credito", "status": "received" },
    "lastUpdate": "2026-06-15T19:12:24.391Z"
  }
}

Reply (nós → PIED)

Responder 200 OK rápido (apenas confirma o recebimento; o processamento é assíncrono).

HTTP/1.1 200 OK

⚠️ Lacunas (NÃO disparam webhook)

Alteração de responsável, edição de frete, campos customizados, anotações e upload de arquivos. Consequência: o webhook não é um espelho fiel — o que falta é coberto pela reconciliação via REST (Anexo A).

Segurança (a confirmar com a PIED)

• Sem assinatura/HMAC documentada → estratégia: segredo compartilhado + lista de IPs + HTTPS.
• Política de reenvio (retry) não documentada → assumir "pode perder evento" e cobrir com a reconciliação REST.

Pontos em aberto detalhados em ../../PENDENCIAS.md.