> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onbeef.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Receba webhooks de pedidos

> Receba notificações quando pedidos forem criados ou mudarem de status.

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`](/api-reference/merchant/update-merchant). 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`](/api-reference/orders/get-events).

<Note>
  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.
</Note>

## 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:

```json theme={null}
{
  "ordersWebhookURL": "https://your-pos-system.example.com/onbeef"
}
```

A Onbeef enviará as notificações para:

```http theme={null}
POST https://your-pos-system.example.com/onbeef/v1/orderUpdate
Content-Type: application/json
```

<Warning>
  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.
</Warning>

## 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.

<Warning>
  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`.
</Warning>

## Payload

A Onbeef envia o corpo como `application/json`:

```json theme={null}
{
  "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.

```text theme={null}
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.

<Warning>
  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.
</Warning>

## 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.

<Warning>
  Use [`GET /v1/events:polling`](/api-reference/orders/get-events) 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.
</Warning>