> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.konfidency.cx/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Configurar Webhook na plataforma Vnda

Este passo a passo configura a plataforma Vnda para nos avisar, em tempo real, sempre que um pedido for **confirmado**, **cancelado** ou **entregue**.

## Por que isso é necessário

Sem os webhooks, a Konfidency depende apenas de consultas periódicas à API da Vnda, que retornam pedidos por **data de criação**. Na prática, isso significa que a confirmação do pedido costuma ser capturada, mas a **entrega** — que acontece dias depois — não é.

Isso importa porque a régua de avaliação pode ser ancorada em diferentes gatilhos: a confirmação do pedido, a previsão de entrega ou a entrega efetiva. A **entrega efetiva é o gatilho mais preciso** — é o único que garante que o consumidor já recebeu o produto quando o convite chega — e é o que recomendamos. Se a sua régua usa esse gatilho e a data de entrega não chega até nós, o convite simplesmente não é disparado.

Com os webhooks configurados, a própria Vnda nos notifica a cada mudança de status, eliminando essa lacuna.

## Pré-requisitos

* Acesso de administrador ao Admin da Vnda.
* O **identificador da loja na Konfidency** (por exemplo, `sualoja`). Ele faz parte da URL do webhook e você pode consultar no Dashboard em Configurações > Integrações > API. Não invente nem adapte esse valor: se estiver errado, os eventos são recusados.

## Passo a passo

Repita a operação abaixo **uma vez para cada um dos três eventos** da tabela.

1. Acesse o Admin da plataforma Vnda.
2. Clique no ícone de **Configurações**, no canto inferior esquerdo.
3. Na seção **Integrações**, clique em **Webhooks**.
4. Clique em **+ Adicionar webhook**.
5. Preencha os campos da janela *Adicionar novo webhook*:
* **Evento:** um dos três eventos da tabela abaixo.
* **URL:** https://webhooks.konfidency.com.br/vnda/{IDENTIFICADOR}/order-status
     *(substitua `{IDENTIFICADOR}` pelo identificador da loja –* você pode consultar no Dashboard em Configurações > Integrações > API
6. Clique em **Salvar**.

### Eventos a configurar

Os três eventos usam **exatamente a mesma URL**. Muda apenas o evento selecionado.

| Evento | Quando dispara | Para que serve na Konfidency |
| ---- |
| `order-confirmed` | Pedido confirmado (pagamento aprovado) | Registra o pedido e os produtos comprados |
| `package-delivered` | Pacote entregue ao consumidor | **Marca o pedido como entregue** |
| `order-canceled` | Pedido cancelado | Impede o envio de convite para pedido cancelado |

> **O evento `package-delivered` é o mais importante dos três.** É ele que informa a data de entrega. Se a sua régua usa a entrega como gatilho (a configuração que recomendamos), sem esse evento os convites não são gerados, mesmo com os outros dois configurados.

### Exemplo preenchido

Para uma loja cujo identificador na Konfidency seja `sualoja`:

| Evento | URL |
| ---- |
| `order-confirmed` | https://webhooks.konfidency.com.br/vnda/sualoja/order-status |
| `package-delivered` | https://webhooks.konfidency.com.br/vnda/sualoja/order-status |
| `order-canceled` | https://webhooks.konfidency.com.br/vnda/sualoja/order-status |

## Atenção: erros comuns

**A URL precisa ter o identificador da loja.** A URL abaixo está **incorreta**: ela responde "página não encontrada" a cada evento, silenciosamente, sem nenhum aviso no Admin da Vnda. Se você recebeu de nós uma orientação anterior sem o identificador no endereço, refaça o cadastro com a URL correta.

```
❌ https://webhooks.konfidency.com.br/vnda/order-status
✅ https://webhooks.konfidency.com.br/vnda/sualoja/order-status
```

Outros pontos de atenção:

* Não use http://, apenas https://.
* Não acrescente barra no final da URL.
* Confira se não há espaço em branco no início ou no fim do campo.
* Os três eventos são cadastros separados, com a mesma URL. Não é possível selecionar mais de um evento por webhook.

## Depois de configurar

Avise o time da Konfidency. Nós confirmamos do nosso lado que os eventos estão chegando, geralmente em poucos minutos após o primeiro pedido confirmado ou entregue.

Para testar sem esperar um pedido novo, o Admin da Vnda permite **reenviar** um evento a partir do código de um pedido já existente.

> **Importante:** o webhook passa a valer para os eventos que acontecerem **a partir de agora**. Pedidos que já foram entregues antes da configuração não geram convite automaticamente, porque o evento de entrega deles já passou. Se você quiser recuperar esses pedidos, avise o time da Konfidency — conseguimos fazer uma carga retroativa manualmente.