Webhook do PDV

Quer que o seu sistema saiba na hora que um pedido foi confirmado, pago, despachado ou entregue — ou que um produto chegou ao estoque mínimo? O Webhook do PDV avisa o seu sistema a cada evento de pedido, pagamento, caixa, estoque, entrega e taxa de entrega do PDV.

O Webhook do PDV cobre só o PDV. As conversas com os clientes são avisadas pelos webhooks da Conexão e do Setor.

Onde ligar

Webhook do PDV (recebe os eventos de pedidos, pagamentos, caixa e estoque): o endereço que recebe todos os eventos do PDV da empresa. Em branco, nada é enviado. Ao salvar, a tela avisa "Webhook do PDV salvo." e lista os eventos enviados.

O endereço precisa começar com http:// ou https://, sem espaços, e não pode apontar para a rede interna. Ele recebe POST com corpo em JSON.

O campo que separa um aviso do outro

Tudo chega no mesmo endereço, e é o acao que diz o que aconteceu no PDV:

Todo aviso do Webhook do PDV traz também:

companyId — a empresa.

origem — de onde veio o evento, como painel (alguém na tela).

enviadoEm — a hora em que o aviso foi enviado.

backendURL — o endereço do backend da sua instalação.

Exemplo de payload de Pedido

O aviso de um pedido que saiu para entrega:

{
  "acao": "pedido-saiu",
  "companyId": 8,
  "pedido": {
    "id": 42,
    "numero": 42,
    "situacao": "saiu",
    "ticketId": 1207,
    "ticket": {
      "id": 1207,
      "uuid": "3f2a9c1e-5b7d-4e8a-9c0f-1a2b3c4d5e6f",
      "status": "open"
    },
    "contato": {
      "id": 399,
      "nome": "Maria Cliente",
      "numero": "5511999990000"
    },
    "vendedor": {
      "id": 16,
      "nome": "Ana Vendas"
    },
    "subtotal": 35.9,
    "descontoTipo": "valor",
    "descontoValor": 0,
    "desconto": 0,
    "acrescimo": 0,
    "entrega": "entrega",
    "taxaEntrega": 7.5,
    "enderecoEntrega": "Rua das Flores, 100",
    "bairroEntrega": "Centro",
    "agendadoPara": null,
    "observacao": null,
    "total": 43.4,
    "itens": [
      {
        "id": 25,
        "productId": 1,
        "nome": "Caneca",
        "sku": "CAN001",
        "tipo": "produto",
        "quantidade": 1,
        "precoUnitario": 35.9,
        "total": 35.9,
        "estoque": 21
      }
    ],
    "quantidadeDeItens": 1,
    "pagamento": "pendente",
    "valorPago": 0,
    "saldo": 43.4,
    "pagoEm": null,
    "pagamentos": [],
    "confirmadoEm": "2026-10-28T15:50:19.459Z",
    "enviadoEm": "2026-10-28T15:50:19.672Z",
    "preparandoEm": "2026-10-28T15:50:41.028Z",
    "prontoEm": "2026-10-28T15:50:49.637Z",
    "saiuEm": "2026-10-28T15:51:01.433Z",
    "entregueEm": null,
    "canceladoEm": null,
    "canceladoPor": null,
    "motivoCancelamento": null,
    "entregador": {
      "id": 30,
      "nome": "Carlos Entregas"
    },
    "comprovanteDaEntrega": null,
    "naoEntregue": null,
    "balcao": false,
    "rastreio": "https://seu-painel.com.br/rastreio/AbC123",
    "destino": null,
    "previsaoChegada": null,
    "createdAt": "2026-10-28T15:50:19.378Z"
  },
  "origem": "painel",
  "enviadoEm": "2026-10-28T15:51:01.464Z",
  "backendURL": "https://backend_url.com.br"
}

pedido — o pedido inteiro: número, situação, cliente (contato), quem vendeu (vendedor), os valores, a entrega com o bairro e os itens, cada um com o estoque depois da venda.

pedido.situacao — rascunho, confirmado, preparando, pronto, saiu, entregue ou cancelado; as horas de cada etapa ficam em confirmadoEm, preparandoEm, prontoEm, saiuEm e entregueEm.

pedido.pagamento — pendente, em parte ou pago; valorPago e saldo dizem quanto entrou e quanto falta.

pedido.entregador e pedido.rastreio — quem leva o pedido e o link do rastreio do cliente; comprovanteDaEntrega traz a localização e a foto depois da entrega.

pedido.agendadoPara — a data e o horário combinados, no pedido agendado; pedido.balcao é true na venda de balcão.

pedido.ticket — o atendimento onde o pedido foi montado; vazio na venda de balcão.

O que cada aviso traz a mais

Pagamento: pagamento, com a forma, o valor, o valor recebido, o troco e a situação.

Caixa: caixa, com o fundo de troco e o esperado de cada forma; no fechamento, também o contado e a diferença.

Estoque (estoque-movimentado e estoque-baixo): movimento (tipo, quantidade, saldo anterior e posterior, motivo e o pedido) e produto (estoque, estoque mínimo e estoqueBaixo).

Não entregue (pedido-nao-entregue): o pedido, que volta à situação pronto, mais entregador e motivo.

Posição do entregador (entregador-posicao): entregador, posicao (latitude, longitude, precisão e a hora) e pedidos, os pedidos que estão com ele.

Taxa de entrega: taxa, com o bairro e o valor.

Como saber que o aviso veio daqui

Todo aviso do Webhook do PDV traz o cabeçalho X-Pdv-Evento, com o evento, e vai assinado com o Token da Empresa no cabeçalho X-Assinatura-Pdv. O token não vai no corpo do aviso.