Pular para o conteúdo principal
Com o webhook, a DeliveryVip faz um POST com o evento em JSON na sua URL assim que ele acontece. Você recebe eventos de pedido e de indoor (chamar garçom, pedir a conta) sem fila para drenar, sem limite de 100 eventos e sem intervalo de consulta.
Webhook e polling são independentes: receber um evento por webhook não o remove do polling, e vice-versa. Eventos entregues por webhook não precisam de acknowledgment.Use o webhook como canal principal e o polling como reconciliação: se o seu endpoint ficar fora do ar, os eventos das últimas 24 horas continuam disponíveis no polling.

Como configurar

1

Abra a sua aplicação

No painel do desenvolvedor, abra a aplicação que integra com as lojas.
2

Informe a URL de notificação

Na seção Webhook, preencha a URL de notificação com o endpoint do seu sistema que vai receber os eventos e salve.
Seção Webhook do painel, com o campo URL de notificação preenchido

Seção Webhook: informe a URL de notificação e salve

3

Responda 2xx

O seu endpoint precisa aceitar POST e responder com um status 2xx para confirmar o recebimento.
A aplicação tem uma única URL de webhook. Os eventos de todas as lojas que instalaram o seu app chegam nela; identifique a loja pelo header X-App-MerchantId ou pelo campo merchantId do corpo.
Apps com a extensão Open Delivery podem ter uma URL e um secret por loja. Veja Recebendo eventos no guia Open Delivery.

A requisição

Cada evento chega numa requisição própria:
string
obrigatório
HMAC-SHA256 do corpo bruto da requisição, em hexadecimal minúsculo. Veja Validando a origem.
string
obrigatório
A loja do evento: o merchantId que você configurou para ela, quando houver, ou o id da loja na DeliveryVip. É o mesmo valor do campo merchantId do corpo.
string
obrigatório
Identificador fixo da DeliveryVip como plataforma emissora: 019efa90-dcd1-7846-983d-6bab871b2f6b. É o mesmo em todas as entregas, para todos os apps, e não é o id do seu app. Serve como checagem simples de origem; quem garante a autenticidade é a assinatura.

Validando a origem

O header X-App-Signature é o HMAC-SHA256 do corpo bruto, em hexadecimal minúsculo, usando o Client Secret da sua aplicação como chave. Recalcule a assinatura sobre o corpo recebido e compare com o header usando comparação de tempo constante.
Calcule a assinatura sobre o corpo exato recebido, antes de qualquer parse. Fazer parse e serializar de novo muda os bytes, e a assinatura deixa de bater.
Rejeite toda requisição cuja assinatura não confere. A assinatura é a única prova de que o evento veio da DeliveryVip; sem ela, qualquer um consegue forjar eventos de pedido no seu endpoint.
Ao renovar o Client Secret, a troca vale na hora: toda entrega enviada depois, incluindo tentativas automáticas e reenvios manuais, já é assinada com o novo secret.

O corpo do evento

O corpo é um único evento, no mesmo formato que o polling devolve.
uuid
obrigatório
Identificador único do evento. Use-o para descartar entregas repetidas.
string
obrigatório
Tipo do evento, em maiúsculas. Veja os tipos.
string
obrigatório
A loja do evento.
datetime
obrigatório
Quando o evento aconteceu, em RFC 3339 com o fuso de Brasília (-03:00). Para lojas integradas pelo Open Delivery, vem em UTC (sufixo Z).
object
Dados extras de alguns eventos, como o motivo de um cancelamento. Chaves em camelCase. Só vem quando há conteúdo.
uuid
Eventos de pedido. O pedido ao qual o evento pertence.
string
Eventos de pedido. URL para buscar os detalhes do pedido.
string
Eventos de pedido. DELIVERY, TAKEOUT ou INDOOR.
string
Eventos de indoor. A mesa ou a comanda que gerou o evento. Cada campo só vem quando está preenchido.

Tipos de evento

PICKUP_AREA_ASSIGNED, CANCELLATION_REQUESTED, CANCELLATION_REQUEST_DENIED e ORDER_CANCELLATION_REQUEST estão previstos na especificação, mas ainda não são emitidos. Se chegar um tipo que você não conhece, responda 2xx e ignore.

O que o seu endpoint deve fazer

  • Validar a assinatura antes de qualquer processamento.
  • Responder 2xx rápido. Grave o evento e processe de forma assíncrona: a DeliveryVip desiste após 3 segundos para conectar e 5 segundos para receber a resposta, e conta isso como falha.
  • Descartar repetidos pelo eventId. A assinatura não tem timestamp e o mesmo evento pode chegar de novo numa nova tentativa ou num reenvio manual.

Tentativas e reenvio

Entregas com falha podem ser reenviadas manualmente no painel. Enquanto ainda há tentativas automáticas em curso, o reenvio manual fica indisponível para evitar entregas duplicadas.
Se o seu servidor estiver sobrecarregado e quiser que a DeliveryVip tente de novo, responda 429 ou 408, não 500 ou 503.

Suspensão automática

Após 10 falhas consecutivas, a DeliveryVip suspende o envio de webhooks da sua aplicação e avisa por e-mail, com o motivo da última falha. Cada tentativa que falha conta; uma entrega bem-sucedida zera o contador.
Enquanto o envio está suspenso, os eventos continuam disponíveis no polling. Para retomar:
1

Corrija o endpoint

Confirme que a URL responde 2xx para um POST com corpo JSON.
2

Reative o envio

No painel do desenvolvedor, abra a aplicação e entre em Ver webhooks enviados. No aviso Envio de webhooks suspenso, clique em Reativar envios.
3

Reenvie o que falhou

Na mesma tela, filtre por Com falha e reenvie as entregas que você precisa.

Acompanhamento

A tela Webhooks enviados (painel do desenvolvedor, sua aplicação, Ver webhooks enviados) mostra o histórico de entregas: tipo do evento, loja, status HTTP e número de tentativas. Filtre por Com falha ou Sucesso e reenvie as entregas que falharam.
Tela Webhooks enviados com histórico de entregas e botões de reenvio

Tela Webhooks enviados: histórico, status HTTP, tentativas e reenvio

Erros comuns

Quase sempre o corpo foi transformado antes do cálculo: o framework fez parse do JSON e você serializou de novo. Leia o corpo bruto (express.raw, request.get_data(), request.raw_post) e calcule o HMAC sobre esses bytes. Confira também se está usando o Client Secret da aplicação, e não o Client ID.
É esperado: novas tentativas e reenvios manuais repetem o mesmo eventId, e o mesmo evento também aparece no polling. Guarde os eventId processados e descarte os repetidos.
O seu endpoint acumulou 10 falhas seguidas. Corrija o endpoint, clique em Reativar envios na tela Webhooks enviados e reenvie as entregas com falha. Enquanto isso, recupere os eventos pelo polling.
Respostas 5xx não são tentadas de novo automaticamente. Reenvie pelo painel ou recupere o evento pelo polling. Para pedir uma nova tentativa automática, responda 429 ou 408.