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

# receber notificações

> estrutura do payload e como processar webhooks

cada notificação é uma requisição `POST` com este corpo:

```json theme={null}
{
  "eventId": "5ebcd63c-0cf2-4f45-82cc-07440eb9427d",
  "eventType": "customer.status.draft",
  "eventVersion": "1.0",
  "timestamp": "2026-04-16T11:53:00.245Z",
  "subscriptionId": "a8fa74b1-af91-4dde-b68b-82e06e1d51a1",
  "brand": {
    "id": "5d84bfd8-c9ae-44bc-acfb-dbc1721fa1be",
    "name": "nome da marca"
  },
  "entity": {
    "type": "customer",
    "id": "e6892af7-75d6-4036-8779-9d2ad1336dab",
    "href": "https://integration.teceo.co/v1/customers/e6892af7-75d6-4036-8779-9d2ad1336dab"
  },
  "data": {
    "commercialName": "Loja Centro",
    "previousStatus": "PENDING",
    "currentStatus": "DRAFT"
  },
  "metadata": {
    "changedBy": {
      "type": "user",
      "id": "30cac3a9-ceb1-46db-bd94-038c8a7f9331",
      "name": "Nome do Usuário"
    }
  }
}
```

## campos

<ResponseField name="eventId" type="string" required>
  identificador único do evento (uuid).
</ResponseField>

<ResponseField name="eventType" type="string" required>
  tipo do evento. exemplo: `customer.status.draft`.
</ResponseField>

<ResponseField name="eventVersion" type="string" required>
  versão do schema do evento.
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  data e hora em que o evento ocorreu (iso 8601).
</ResponseField>

<ResponseField name="subscriptionId" type="string" required>
  identificador da assinatura (uuid).
</ResponseField>

<ResponseField name="brand" type="object" required>
  marca onde o evento ocorreu.

  <Expandable title="propriedades de brand">
    <ResponseField name="id" type="string" required>
      uuid da marca.
    </ResponseField>

    <ResponseField name="name" type="string" required>
      nome da marca.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="entity" type="object" required>
  entidade relacionada ao evento.

  <Expandable title="propriedades de entity">
    <ResponseField name="type" type="enum<string>" required>
      tipo da entidade. valores possíveis: `customer`, `order`, `case`.
    </ResponseField>

    <ResponseField name="id" type="string" required>
      uuid da entidade.
    </ResponseField>

    <ResponseField name="href" type="string" required>
      link rápido para obter os dados completos via api teceo.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object" required>
  dados do evento. a estrutura varia conforme o `eventType`.
</ResponseField>

<ResponseField name="metadata" type="object" required>
  metadados adicionais do evento.

  <Expandable title="propriedades de metadata">
    <ResponseField name="changedBy" type="object" required>
      quem originou a ação.

      <Expandable title="propriedades de changedBy">
        <ResponseField name="type" type="enum<string>" required>
          origem da ação. valores possíveis: `user` (ação humana) ou `system` (ação automática).
        </ResponseField>

        <ResponseField name="id" type="string" required>
          id do usuário na teceo. `null` se for ação automática (system).
        </ResponseField>

        <ResponseField name="name" type="string" required>
          nome do usuário na teceo. `null` se for ação automática (system).
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## resposta esperada

| código             | o que significa                               |
| ------------------ | --------------------------------------------- |
| `2XX`              | recebido com sucesso — marcamos como entregue |
| `5XX` ou timeout   | erro temporário — tentamos de novo            |
| `4XX` (exceto 429) | erro permanente — não tentamos de novo        |

<Note>responda `2XX` imediatamente e processe em background. o timeout por tentativa é de **10 segundos**.</Note>

se configurou um signing secret, valide a assinatura antes de processar. veja [assinando requisições](./assinando-requisicoes).