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.


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 é oclient_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.
- 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.
Polling (reconciliação)
Consultar eventos
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 oeventId de cada evento no campo id.
Resposta (202)
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.