Receba webhooks de pedidos - Onbeef Connect API

A Onbeef envia uma notificação quando um pedido é criado ou muda de status. Use o webhook para receber esses eventos sem depender apenas do polling.

Ative o webhook

Registre ordersWebhookURL com PUT /v1/merchantOnboarding. O envio das notificações começa quando existe uma URL registrada. Sem ordersWebhookURL, a Onbeef não envia webhooks. Nesse caso, acompanhe os pedidos por polling com GET /v1/events:polling.

O webhook complementa o polling. Continue usando GET /v1/events:polling como rede de segurança para verificar o estado atual dos pedidos quando uma notificação não chegar.

Configure a URL

ordersWebhookURL deve conter a URL base do seu servidor. Não inclua /v1/orderUpdate nem uma barra no final. Por exemplo, registre:

{
  "ordersWebhookURL": "https://your-pos-system.example.com/onbeef"
}

A Onbeef enviará as notificações para:

POST https://your-pos-system.example.com/onbeef/v1/orderUpdate
Content-Type: application/json

Não registre a URL final do webhook. Se você informar https://your-pos-system.example.com/onbeef/v1/orderUpdate, a Onbeef acrescentará o caminho novamente.

Eventos enviados

A Onbeef envia uma notificação nestas situações:

Um pedido é criado.
O status de um pedido muda.

Cada notificação contém um único evento.

A mesma notificação pode ser entregue mais de uma vez, inclusive sem mudança de estado (por exemplo, em cancelamentos, que geram duas notificações). Processe de forma idempotente usando o par orderId e eventId.

Payload

A Onbeef envia o corpo como application/json:

{
  "orderId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "eventId": "d6703cc8-9e79-415d-ac03-a4dc7f6ab43c",
  "eventType": "CREATED",
  "orderURL": "https://api.connect.onbeefapp.com.br/v1/orders/f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "createdAt": "2026-08-06T14:15:22.000000Z",
  "sourceAppId": "fb08c6b7-a844-43c6-b104-98e70c00fc20",
  "virtualBrand": null
}

Campo	Descrição
`orderId`	Identificador do pedido. Use junto com `eventId` para identificar este evento de pedido.
`eventId`	Identificador do tipo de evento. O mesmo valor é compartilhado por todos os pedidos com o mesmo `eventType`. Nunca use apenas este campo para deduplicar eventos.
`eventType`	Tipo do evento de pedido.
`orderURL`	URL para consultar os dados completos do pedido.
`createdAt`	Data e hora de criação do pedido.
`sourceAppId`	Identificador da aplicação que originou o evento.
`virtualBrand`	Marca virtual associada ao pedido. Atualmente, o valor é sempre `null`.

A identidade de um evento é o par orderId e eventId. Armazene e deduplique sempre por esse par.

Headers

Cada notificação inclui estes headers:

Header	Descrição
`Content-Type`	Sempre `application/json`.
`X-App-Id`	Identificador da aplicação na Onbeef.
`X-App-MerchantId`	Identificador do seu merchant.
`X-App-Signature`	Assinatura HMAC-SHA256 hexadecimal do corpo JSON bruto.

Valide a assinatura

Você deve validar X-App-Signature antes de processar a notificação. Calcule o HMAC-SHA256 sobre o corpo bruto recebido. Use o client_secret da sua integração como chave. O resultado é uma string hexadecimal de 64 caracteres.

X-App-Signature = hex(hmac_sha256(corpo_bruto, client_secret))

Compare o resultado com o valor de X-App-Signature. Use uma comparação em tempo constante quando sua linguagem oferecer esse recurso.

Calcule a assinatura antes de desserializar ou modificar o JSON. Alterações em espaços, quebras de linha ou ordem dos campos produzem outra assinatura.

Responda rapidamente

Responda com um status 2xx assim que validar e armazenar a notificação. Processe o evento de forma assíncrona sempre que possível. A Onbeef não reenvia a notificação quando seu servidor está indisponível ou responde com erro.

Use GET /v1/events:polling como rede de segurança para verificar o estado atual dos pedidos. O polling retorna o evento mais recente de cada pedido, não um histórico. Se uma notificação não chegar e o pedido avançar, o polling retornará o estado mais novo. O estado intermediário não será recuperado.

​Ative o webhook

​Configure a URL

​Eventos enviados

​Payload

​Headers

​Valide a assinatura

​Responda rapidamente

Ative o webhook

Configure a URL

Eventos enviados

Payload

Headers

Valide a assinatura

Responda rapidamente