Receba eventos de pedido e de indoor em tempo real na sua URL, valide a assinatura e trate reenvios e suspensões.
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.
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: 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.
POST {sua URL de notificação}Content-Type: application/jsonUser-Agent: DeliveryVipX-App-Id: 019efa90-dcd1-7846-983d-6bab871b2f6bX-App-MerchantId: 8158198a-4bb7-430e-9746-87cd02dfeddaX-App-Signature: 5d41402abc4b2a76b9719d911017c592...
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.
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.
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.
import crypto from 'node:crypto'import express from 'express'const app = express()// express.raw mantém o corpo exatamente como chegouapp.post('/webhooks/deliveryvip', express.raw({ type: 'application/json' }), (req, res) => { const expected = crypto.createHmac('sha256', process.env.CLIENT_SECRET).update(req.body).digest('hex') const received = req.get('X-App-Signature') ?? '' const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected)) if (!valid) return res.sendStatus(401) const event = JSON.parse(req.body) queue.push(event) // processe depois, fora da requisição res.sendStatus(200)})
import hashlibimport hmacimport osfrom flask import Flask, abort, requestapp = Flask(__name__)@app.post("/webhooks/deliveryvip")def deliveryvip_webhook(): raw_body = request.get_data() # bytes exatamente como chegaram expected = hmac.new(os.environ["CLIENT_SECRET"].encode(), raw_body, hashlib.sha256).hexdigest() if not hmac.compare_digest(expected, request.headers.get("X-App-Signature", "")): abort(401) queue.put(request.get_json()) # processe depois, fora da requisição return "", 200
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.
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.
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.
Tenta de novo automaticamente, até 3 tentativas no total. Se todas falharem, a entrega fica como falha.
Qualquer outro status, inclusive 5xx
Marca a entrega como falha na hora, sem nova tentativa automática.
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.
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.
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: histórico, status HTTP, tentativas e reenvio
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.
Recebo o mesmo evento duas vezes
É 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 envio foi suspenso
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.
Meu endpoint retornou 500 e o evento não voltou
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.
Assistant
Responses are generated using AI and may contain mistakes.