Webhook de Eventos de Pedidos

Esta seção descreve o endpoint de webhook do OpenDelivery, usado pela Ordering Application para notificar o Software Service da Goomer sobre eventos do ciclo de vida dos pedidos.

Visão Geral

Nesta rota a Ordering Application envia uma requisição POST para cada novo evento de pedido. A URL do webhook é informada ao integrador durante o onboarding do merchant.

Endpoint Principal

Método	Endpoint	Descrição
POST	/opendelivery/v1/newEvent	Recebe um evento de pedido enviado pela Ordering Application

Autenticação (Assinatura de Webhook)

O webhook não utiliza OAuth. A autenticidade da requisição é garantida por três headers obrigatórios:

Header	Tipo	Obrigatório	Descrição
x-app-id	string	Sim	Identificador único da Ordering Application
x-app-merchantid	string	Sim	Identificador único do merchant (formato {document}-{UUID})
x-app-signature	string (SHA256)	Sim	HMAC-SHA256 do raw body usando o client secret como chave

Importante: A Goomer preserva o raw body recebido para validar a assinatura. Proxies ou middlewares que reescrevem o corpo da requisição invalidam a verificação.

Limites de Uso (Rate Limiting)

Limite	Janela de Tempo
100 requisições	1 minuto

Quando excedido, retorna HTTP 429.

Estrutura do Payload

Campos comuns a todos os eventos

Campo	Tipo	Obrigatório	Descrição
eventId	string (UUID)	Sim	Identificador único do evento
eventType	string (enum)	Sim	Tipo do evento (ver tabela abaixo)
orderId	string (UUID)	Sim	Identificador do pedido (gerado pela Ordering Application)
orderURL	string (URI)	Sim	URL para obter os detalhes do pedido
createdAt	string (ISO 8601)	Sim	Data/hora de criação do evento (UTC)
sourceAppId	string (UUID)	Não	AppId da Ordering Application originadora (usado por Hubs)
virtualBrand	string	Não	Identificação alternativa do merchant (dark kitchens, multi-marca)

Tipos de Evento

Tipo	Descrição
CREATED	Pedido criado
CONFIRMED	Pedido confirmado pelo estabelecimento
PREPARATION_REQUESTED	Preparação solicitada
PREPARING	Pedido em preparação
DISPATCHED	Pedido despachado para entrega
READY_FOR_PICKUP	Pronto para retirada
PICKUP_AREA_ASSIGNED	Área de retirada atribuída
PICKED_UP	Retirado pelo entregador
DELIVERED	Entregue ao cliente
CONCLUDED	Concluído
CANCELLATION_REQUESTED	Cancelamento solicitado
CANCELLATION_REQUEST_DENIED	Solicitação de cancelamento negada
CANCELLED	Pedido cancelado
ORDER_CANCELLATION_REQUEST	Solicitação de cancelamento de pedido
CANCELLED_DENIED	Cancelamento do pedido negado

Exemplo de Requisição

POST /opendelivery/v1/newEvent HTTP/1.1
Host: partner-api.goomer.app
Content-Type: application/json
x-app-id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
x-app-merchantid: 12345678901234-550e8400-e29b-41d4-a716-446655440000
x-app-signature: 4b3c2d1e...

{
  "eventId": "abb14b1f-f1c8-4706-8016-ad353e15216a",
  "eventType": "CREATED",
  "orderId": "00cf66ff-429d-4c61-9872-0fa5f2a3b66a",
  "orderURL": "https://partner-api.goomer.app/opendelivery/v1/orders/00cf66ff-429d-4c61-9872-0fa5f2a3b66a",
  "createdAt": "2025-06-24T16:53:54.433Z"
}

Comportamento de Retry e Idempotência

• A Goomer responde com 204 No Content quando o evento é aceito para processamento assíncrono.
• Se a resposta não for 2xx, espera-se que a Ordering Application reenvie o evento conforme sua política de retry.
• Eventos com o mesmo eventId são tratados idempotentemente — reenvios não duplicam efeitos no estado interno.

Códigos de Status

Código	Descrição
204	Evento aceito
400	Payload inválido (eventType desconhecido, campos obrigatórios faltando, etc.)
403	Assinatura inválida ou headers ausentes
404	Merchant não encontrado para os identificadores fornecidos
429	Limite de requisições excedido

Documentação Completa

Para o schema OpenAPI completo, consulte a documentação técnica de referência.