Skip to main content
A DeliveryVip entrega eventos de pedido pelos dois métodos previstos na spec Order 1.3.0: WEBHOOK e POLLING. Recomendamos 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 seguem consultáveis no polling.
A DeliveryVip envia o evento assinado ao webhook, o PDV responde 2xx em até 5 s e reconcilia pelo polling com acknowledgmentA DeliveryVip envia o evento assinado ao webhook, o PDV responde 2xx em até 5 s e reconcilia pelo polling com acknowledgment

Webhook como canal principal e polling como reconciliação

Estrutura do evento

string
Identificador único do evento. Use para deduplicação e no acknowledgment.
string
Tipo do evento; veja a lista abaixo.
string
Identificador do pedido.
string
URL do pedido na API OD. Use-a para obter os detalhes.
string
DELIVERY, TAKEOUT ou INDOOR.
string
O merchantId configurado no onboarding, ou o id interno da loja, se não configurado.
string
Data e hora do evento em RFC 3339, em UTC (sufixo Z), tanto no polling quanto no webhook. Veja Datas e horários.
object
Dados extras de alguns eventos, como o motivo de um cancelamento. Só vem quando há conteúdo.

Tipos de evento

PICKUP_AREA_ASSIGNED, CANCELLATION_REQUESTED, CANCELLATION_REQUEST_DENIED e ORDER_CANCELLATION_REQUEST existem na spec e são aceitos no filtro eventType, mas a DeliveryVip ainda não os emite. Trate tipos desconhecidos confirmando o recebimento e seguindo em frente.

Webhook (canal principal)

A URL de webhook é configurada por loja, no onboarding (ordersWebhookURL) ou pelo formulário do painel de developers. Lojas sem URL própria caem na URL de webhook geral do app, se você tiver configurado uma. Cada evento é enviado individualmente via POST na URL da loja, com o mesmo JSON dos eventos do polling e os headers:

Validando a assinatura

A chave é o client_secret da loja que você recebeu na instalação, o mesmo que você usa para pedir o token dela. Use o X-App-MerchantId para descobrir de qual loja é o evento e escolher o secret certo. Só lojas sem credencial própria (integrações antigas, anteriores à extensão Open Delivery) são assinadas com o client_secret do app. Recompute o HMAC sobre o corpo bruto recebido, antes de qualquer parse, e compare com o header em tempo constante:
Valide sobre os bytes como chegaram. Fazer parse e re-serializar o JSON muda espaçamento, escapes e números, e o digest não bate. A assinatura cobre só o corpo e não tem timestamp: um reenvio repete o mesmo eventId, por isso a deduplicação é obrigatória.

O que seu endpoint deve fazer

  • Responder 2xx em até 5 segundos (3 s para conectar, 5 s para ler). Se o processamento for demorado, processe de forma assíncrona.
  • Validar a assinatura antes de processar.
  • Deduplicar por eventId.

Reentrega e suspensão

  • Toda tentativa que falha conta para a suspensão, inclusive as retentativas. Uma entrega bem-sucedida zera a contagem.
  • Após 10 falhas consecutivas as entregas daquela loja são suspensas (você é notificado por e-mail, com o nome da loja). As demais lojas continuam recebendo normalmente.
Para religar as entregas de uma loja suspensa, depois de corrigir o endpoint:
  • reenvie o onboarding da loja; ou
  • use o botão “Reativar envio de webhooks” no painel de developers; ou
  • salve novamente os dados da loja no formulário do painel.
Enquanto as entregas estiverem suspensas, os eventos continuam disponíveis no polling por 24 horas. Use-o para recuperar o que ficou para trás.

Polling (reconciliação)

Consultar eventos

Retorna os eventos das últimas 24 horas ainda não confirmados pelo seu app, no máximo 100 por chamada, sempre do mais antigo para o mais recente. Quando não há eventos, a resposta é 204 No Content.
Fila com mais de 100 eventos. Se a resposta vier com 100 eventos, há mais eventos pendentes na fila: envie o acknowledgment e consulte novamente imediatamente, até receber menos de 100 eventos (ou 204).

Filtros

Os filtros podem ser combinados, e um valor inválido em qualquer filtro retorna 403 Forbidden. Os parâmetros de array seguem a serialização padrão da spec OpenAPI (style: form, explode: true): repita o parâmetro na query, uma vez por valor, sem colchetes.
string[]
Tipos de evento: ?eventType=CREATED&eventType=CANCELLED.
string[]
Tipos de pedido, DELIVERY, TAKEOUT ou INDOOR: ?orderType=DELIVERY&orderType=TAKEOUT.
O token por loja já restringe o polling àquela loja, então não é preciso filtrar por loja. O header x-polling-merchants da spec só tem efeito em integrações antigas, com um token para várias lojas.

Acknowledgment

Confirme os eventos processados para que saiam das próximas consultas. Envie um array com o eventId de cada evento no campo id.
Resposta (202)
A operação é idempotente: confirmar o mesmo evento duas vezes não causa erro. Eventos não confirmados continuam sendo retornados (os mais antigos primeiro) até serem confirmados ou saírem da janela de 24 horas.
Eventos entregues por webhook também aparecem no polling até serem confirmados. Se você usa os dois canais, envie o acknowledgment dos eventos já processados via webhook, ou trate o polling como reconciliação deduplicando por eventId.

Erros comuns