Pular para o conteúdo
Endpoints

Eventos

Webhooks

Receba um aviso no seu sistema quando um orçamento é criado: o evento, o formato do aviso, os requisitos da URL e as novas tentativas.

Com um webhook, você não precisa consultar a API o tempo todo para saber se algo mudou. Quando um evento acontece, enviamos um POST para a URL do seu sistema.

Como funciona

  1. O administrador do grupo cadastra o webhook no sistema VendaSimples, com os dados que você informar.
  2. Quando o evento acontece em uma das empresas escolhidas, enviamos um aviso curto para a URL.
  3. Seu sistema responde 2xx e busca os dados completos na API, com o id recebido e o seu token.

O que informar ao administrador

O cadastro de webhooks é feito só pelo administrador do grupo, no sistema: a API não cadastra webhook com o token da integração. Envie a ele:

  • URL: o endereço do seu sistema que vai receber os avisos. Veja Requisitos da URL.
  • Evento: o evento que você quer receber. O evento disponível é o OrcamentoCriado (no sistema, "Orçamento criado").
  • Empresas: em quais empresas do grupo o evento gera aviso (pelo menos uma). Escolha só empresas liberadas para a sua integração: o cadastro do webhook não confere isso, e o pedido de uma empresa não liberada não pode ser consultado.
  • Header adicional (opcional): o nome e o valor de um header que enviamos em todos os avisos. Veja Validar a origem do aviso.
O valor do header adicional funciona como uma senha. Envie-o ao administrador por um canal seguro, não por e-mail ou chat em texto aberto.

O webhook é do grupo, não da integração

O webhook não fica ligado à sua chave de integração. Revogar a integração não desativa o webhook: peça ao administrador para inativá-lo também. O grupo pode ter mais de um webhook, mas não dois ativos com o mesmo evento e a mesma URL.

Evento OrcamentoCriado

Enviado quando um pedido em aberto (orçamento) é criado em uma das empresas do webhook, por qualquer uma destas origens:

  • cadastro de pedido;
  • pedido enviado pelo aplicativo Força de Vendas;
  • pedido gerado a partir de um consignado;
  • junção de pedidos (Juntar Pedidos);
  • cópia de um pedido (Clonar).

O aviso só é enviado depois que o orçamento foi gravado, então ele já pode ser consultado quando o aviso chega. Consulte o pedido pelo id do aviso:

GET/v1/pedido/{id}/abertoConsultar um pedido em aberto Ver na referência

O pedido pode sair de aberto

O orçamento pode ser faturado ou cancelado logo depois do aviso. Nesse caso, a consulta responde 400 com "Pedido não está aberto": o pedido saiu da situação de orçamento e não está mais disponível nesse recurso.

O aviso

HTTP
POST /webhooks/vendasimples HTTP/1.1
Host: seu-sistema.com.br
Content-Type: application/json; charset=utf-8
X-Sua-Chave: valor-que-voce-cadastrou

{
  "evento": "OrcamentoCriado",
  "data": "2026-10-23T13:30:00.1234567Z",
  "idEmpresa": 989,
  "id": 98765
}
X-Sua-Chave é o header adicional, quando cadastrado.
CampoDescrição
eventoNome do evento
dataMomento em que o evento aconteceu, em UTC. Em OrcamentoCriado, é o mesmo momento do dataCriacao do pedido, mas o texto pode diferir nas últimas casas da fração de segundo
idEmpresaEmpresa onde o evento aconteceu
idId do recurso. Em OrcamentoCriado, é o id do pedido

O aviso é curto de propósito: ele só diz o que aconteceu. Os dados completos ficam na API, que exige o token.

Requisitos da URL

  • Usar https.
  • Ter até 2048 caracteres, sem usuário e senha na URL.
  • Apontar para um endereço público, que já resolva no DNS no momento do cadastro. Endereços internos ou privados são recusados no cadastro e também no envio: se o DNS passar a apontar para um deles, o aviso não é enviado.
  • Não usar localhost nem hosts terminados em .localhost, .services.net ou .internal.net.
  • Responder sem redirecionar: respostas 3xx não são seguidas.

Validar a origem do aviso

No cadastro, pode ser definido um header adicional, com nome e valor, que enviamos em todos os avisos. Escolha um valor secreto, informe-o ao administrador e confira esse header no seu sistema para recusar avisos que não vieram de nós.

  • Informe nome e valor, ou nenhum dos dois.
  • Nome: letras sem acento, números e hífen, até 64 caracteres. Exemplo: X-Api-Key.
  • Nomes não permitidos: Host, Content-Type, Content-Length, Transfer-Encoding, Connection, Forwarded e os que começam com Proxy-, X-Forwarded- ou Bredas-.
  • Valor: até 1024 caracteres, sem quebra de linha.

Entrega e novas tentativas

  • Consideramos o aviso entregue quando seu sistema responde qualquer 2xx.
  • Esperamos a resposta por até 30 segundos.
  • Se der erro de rede, tempo esgotado, 5xx ou 429, tentamos de novo depois de 15 segundos, até 5 tentativas no total. O intervalo é sempre de 15 segundos.
  • Outras respostas, como 400, 401, 404 e os redirecionamentos 3xx, não são tentadas de novo.
  • Da primeira à última tentativa passam de cerca de 1 minuto, quando cada tentativa falha na hora, a cerca de 3,5 minutos, quando todas esgotam os 30 segundos.
  • Quando o grupo tem mais de um webhook para o evento, os avisos são enviados um de cada vez: as novas tentativas de um webhook com problema atrasam o envio para os outros.

Dica

Responda 200 assim que receber o aviso e processe depois, em segundo plano. Assim você não estoura os 30 segundos de espera.

Boas práticas

  • Avisos podem chegar repetidos. Isso acontece, por exemplo, quando seu sistema processa o aviso, mas a resposta não chega em 30 segundos. Use evento + id para reconhecer um aviso que você já processou.
  • Avisos podem chegar fora de ordem. Confie nos dados que a API devolve, não na ordem de chegada.
  • Um aviso perdido não é reenviado depois das tentativas. As 5 tentativas cobrem de cerca de 1 a 3,5 minutos, e a API não lista pedidos por período para recuperar um aviso perdido. Mantenha a URL disponível e registre o aviso assim que ele chegar.
  • Confira o header adicional em todo aviso e recuse os que não trouxerem o valor combinado.