<!-- Generated from https://developers.superfrete.com/openapi.yaml (operationId: createWebhook). -->

# Criar Webhook App

> `POST /api/v0/webhook` · Referência interativa: https://developers.superfrete.com/referencia#createWebhook

- **Method:** `POST`
- **Path:** `/api/v0/webhook`
- **Operation ID:** `createWebhook`
- **Tags:** Webhooks

Cadastra uma URL para receber eventos da conta. A SuperFrete envia um `POST` com JSON para essa URL a cada evento assinado em `events`. O formato de cada evento está em [Evento de pedido](https://developers.superfrete.com/referencia/md/orderEvent.md) e [Atualização de rastreio](https://developers.superfrete.com/referencia/md/trackingUpdated.md).

> **Guarde o `secret_token`**
>
> Ele só aparece nesta resposta e serve para validar a assinatura `X-ME-Signature` de cada evento.

## Eventos

| Evento             | Quando é enviado                                                         |
| ------------------ | ------------------------------------------------------------------------ |
| `order.created`    | Etiqueta criada, aguardando pagamento.                                   |
| `order.released`   | Etiqueta paga.                                                           |
| `order.generated`  | Etiqueta gerada na transportadora. A partir daqui há código de rastreio. |
| `order.posted`     | Encomenda postada.                                                       |
| `order.delivered`  | Encomenda entregue.                                                      |
| `order.cancelled`  | Etiqueta cancelada.                                                      |
| `tracking.updated` | Nova movimentação no rastreio.                                           |

Os nomes não são validados na criação: um evento escrito errado é aceito e nunca dispara.

## Effective servers

- `https://sandbox.superfrete.com`

  Sandbox (testes, etiquetas sem validade)
- `https://api.superfrete.com`

  Produção

## Authentication

- **bearerAuth**: HTTP bearer (`JWT`)

  Token de acesso da SuperFrete, no header `Authorization: Bearer {token}`.
  - **Integração da própria loja:** gere o token no painel, em **Integrações** ([produção](https://web.superfrete.com/#/integrations) ou [sandbox](https://sandbox.superfrete.com/#/integrations)).
  - **Plataforma que conecta várias contas:** obtenha um token por seller com o fluxo OAuth 2.0 ([`exchangeOAuthToken`](https://developers.superfrete.com/referencia/md/exchangeOAuthToken.md)).

  O token não expira e dá acesso a todas as rotas da API para a conta; não há escopos. Ele deixa de valer quando a integração é removida no painel. O token de sandbox só funciona no sandbox, e o de produção só em produção.

## Header parameters

- **`User-Agent` (required)**: `string`

  Nome da sua aplicação com um e-mail de contato técnico, no formato `Aplicação (email@exemplo.com)`. Hoje só [Listar pedidos](https://developers.superfrete.com/referencia/md/listOrders.md) recusa um valor fora desse formato, mas envie em todas as rotas.

  **Example:**

  ```json
  "MinhaLoja (dev@minhaloja.com.br)"
  ```

## Request body

**Required:** `true`

**Content type:** `application/json`

- **`name` (required)**: `string`

  Nome para identificar o Webhook App.
- **`url` (required)**: `string`, format: `uri`

  URL `http` ou `https` que vai receber os eventos.
- **`events`**: `array`

  Eventos assinados. Sem este campo, o Webhook App não recebe nada.

  **Items:**

  `string`, possible values: `"order.created", "order.released", "order.generated", "order.posted", "order.delivered", "order.cancelled", "tracking.updated"`

  Evento que dispara a notificação.

**Example:**

```json
{
  "name": "Loja Aurora",
  "url": "https://lojaaurora.com.br/webhooks/superfrete",
  "events": [
    "order.generated",
    "order.posted",
    "order.delivered",
    "tracking.updated"
  ]
}
```

## Responses

### 201 Webhook App criado.

**Content type:** `application/json`

- **`created_at`**: `string`, format: `date-time`
- **`events`**: `array of string`
- **`id`**: `string`
- **`is_active`**: `boolean`
- **`name`**: `string`
- **`secret_token`**: `string`

  Chave da assinatura `X-ME-Signature`. Só aparece nesta resposta.
- **`url`**: `string`

**Example:**

```json
{
  "id": "7hQ2mZk4LwXy9RtB3sVc",
  "name": "Loja Aurora",
  "url": "https://lojaaurora.com.br/webhooks/superfrete",
  "secret_token": "4f9c2a1e8b7d6c5f4e3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e",
  "events": [
    "order.generated",
    "order.posted",
    "order.delivered",
    "tracking.updated"
  ],
  "is_active": true,
  "created_at": "2026-10-29T14:00:00.000Z"
}
```

### 400 `name` ou `url` ausente, URL inválida ou `events` que não é um array.

**Content type:** `application/json`

schema: `ValidationError`

Um ou mais campos da requisição são inválidos.

- **`errors` (required)**: `object`

  Mapa do campo (ex.: `to.postal_code`) para a lista de mensagens de erro desse campo.

  **Additional properties:**

  `array of string`
- **`message` (required)**: `string`

  Sempre `Ocorreu um ou mais erros.`

**Example:**

```json
{
  "message": "",
  "errors": {
    "additionalProperty": [
      ""
    ]
  }
}
```

### 401 Token ausente, inválido, removido ou de outro ambiente.

**Content type:** `application/json`

schema: `Error`

Erro de regra de negócio ou de autenticação. `message` e `error` trazem o mesmo texto.

- **`error` (required)**: `string`

  Mesmo conteúdo de `message`, mantido por compatibilidade.
- **`message` (required)**: `string`

  Mensagem legível do erro.

**Example:**

```json
{
  "message": "Token inválida!",
  "error": "Token inválida!"
}
```

### 500 Erro interno. O corpo pode ser um objeto de erro ou só um texto JSON com a mensagem.

**Content type:** `application/json`

**One of:**

- *Schema `Error` is shown above.*
- `string`

**Example:**

```json
{
  "message": "",
  "error": ""
}
```

## Schemas

- `Error` — shown above.
- `ValidationError` — shown above.

### WebhookEvent

**Type:** `string`, possible values: `"order.created", "order.released", "order.generated", "order.posted", "order.delivered", "order.cancelled", "tracking.updated"`

Evento que dispara a notificação.