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

# Webhooks

> Receba um aviso no seu servidor quando um pré-teste termina, falha ou tem o PDF pronto, e confira a assinatura de cada envio.

Em vez de consultar `GET /pretests/{id}` de tempos em tempos, cadastre um endereço do seu servidor. A Unite faz um `POST` assinado nesse endereço quando algo muda em um pré-teste. O formato segue o padrão [Standard Webhooks](https://www.standardwebhooks.com).

Para gerenciar endpoints pela API, a chave precisa do escopo `webhooks:manage`. Veja [Autenticação](https://docs.myunite.ai/authentication.md). Administradores do workspace também cadastram, testam e removem endpoints no painel do workspace, sem usar chave.

## Eventos

| Evento | Quando acontece |
| - | - |
| `pretest.completed` | A análise terminou e o resultado está disponível. |
| `pretest.failed` | A análise não pôde ser concluída. O pré-teste traz `error.code`. |
| `pretest.report_ready` | O PDF da análise ficou pronto. Em OOH e digital, ele costuma ser gerado sozinho depois de `pretest.completed`. Em e-mail, só é gerado quando alguém pede o PDF (`GET /pretests/{id}/report` ou uma exportação no produto), e o evento chega depois disso. Não espere esse evento para e-mail sem pedir o PDF. |

Cada endpoint escolhe os eventos que quer receber. Há também o evento `ping`, usado só para [testar o endpoint](#testar-o-endpoint).

## Corpo do envio

O corpo é JSON:

```json theme={null}
{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "pretest.completed",
  "createdAt": "2026-11-16T14:32:08.000Z",
  "data": {
    "pretest": {
      "id": "ID_DO_PRETESTE",
      "object": "pretest",
      "status": "completed",
      "channel": "ooh",
      "title": "Verão · relógio urbano"
    }
  }
}
```

* `id`: identifica o evento. É o mesmo valor do cabeçalho `webhook-id`.
* `type`: o tipo do evento.
* `createdAt`: quando o evento ocorreu, em ISO-8601 UTC.
* `data.pretest`: o pré-teste, exatamente como `GET /pretests/{id}` o devolve no momento do evento (o exemplo acima mostra só alguns campos). Veja [Resultados](https://docs.myunite.ai/results.md).

O evento `ping` chega com `data` vazio (`{}`).

## Cabeçalhos

| Cabeçalho | Valor |
| - | - |
| `webhook-id` | Id do evento. Igual em todas as tentativas do mesmo envio. |
| `webhook-timestamp` | Momento do envio, em segundos desde 1970 (Unix). Muda a cada tentativa. |
| `webhook-signature` | `v1,` seguido da assinatura em base64. |
| `content-type` | `application/json` |
| `user-agent` | `Unite-Webhooks/1.0` |

## Criar um endpoint

```bash curl theme={null}
curl -X POST https://myunite.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $UNITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://exemplo.com.br/webhooks/unite",
    "events": ["pretest.completed", "pretest.failed", "pretest.report_ready"],
    "description": "Integração do CRM"
  }'
```

```javascript JavaScript theme={null}
const res = await fetch("https://myunite.ai/api/v1/webhook-endpoints", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNITE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://exemplo.com.br/webhooks/unite",
    events: ["pretest.completed", "pretest.failed", "pretest.report_ready"],
    description: "Integração do CRM",
  }),
});
const endpoint = await res.json();
console.log(endpoint.id, endpoint.secret); // guarde o segredo agora
```

```python Python theme={null}
import os
import requests

res = requests.post(
    "https://myunite.ai/api/v1/webhook-endpoints",
    headers={"Authorization": f"Bearer {os.environ['UNITE_API_KEY']}"},
    json={
        "url": "https://exemplo.com.br/webhooks/unite",
        "events": ["pretest.completed", "pretest.failed", "pretest.report_ready"],
        "description": "Integração do CRM",
    },
)
endpoint = res.json()
print(endpoint["id"], endpoint["secret"])  # guarde o segredo agora
```

A resposta é `201` e traz o endpoint, com `id`, `status` (`enabled` ou `disabled`) e o campo `secret`, no formato `whsec_SEU_SEGREDO_AQUI`.

> [!WARNING]
>
> O segredo aparece **uma única vez**, nesta resposta. A lista de endpoints nunca o devolve. Guarde-o em uma variável de ambiente do seu back-end. Se perder, apague o endpoint e crie outro.

Regras do endereço:

* Precisa usar `https`, na porta 443 (a padrão).
* Não pode ter usuário nem senha.
* Precisa resolver para um endereço público da internet. Endereços privados e locais são recusados.

Um endereço recusado responde [`webhook_url_rejected`](https://docs.myunite.ai/errors#webhook_url_rejected). Cada workspace pode ter até 5 endpoints, ativos ou não. Passando disso, a resposta é [`webhook_endpoint_limit`](https://docs.myunite.ai/errors#webhook_endpoint_limit).

Para listar, use `GET /webhook-endpoints`. Para apagar, `DELETE /webhook-endpoints/{id}`: o endpoint e o histórico de envios dele são removidos, e os envios que ainda esperavam são descartados.

## Verificar a assinatura

Toda requisição vem assinada com o segredo do endpoint. **Confira a assinatura antes de confiar no conteúdo**: qualquer pessoa que descubra o seu endereço pode mandar um `POST` falso.

Use a biblioteca oficial do Standard Webhooks. Ela confere a assinatura e rejeita um `webhook-timestamp` com mais de 5 minutos de diferença, o que barra o reenvio de uma requisição antiga capturada por terceiros.

> [!WARNING]
>
> Assine e confira o corpo **exatamente como chegou** (os bytes crus). Se o seu framework converter o JSON em objeto e depois voltar para texto, a assinatura deixa de bater. Leia o corpo cru antes de qualquer conversão.

```javascript Node (Express) theme={null}
// npm install standardwebhooks express
import express from "express";
import { Webhook, WebhookVerificationError } from "standardwebhooks";

const app = express();
const wh = new Webhook(process.env.UNITE_WEBHOOK_SECRET); // whsec_SEU_SEGREDO_AQUI

// express.raw entrega o corpo cru, sem converter o JSON
app.post("/webhooks/unite", express.raw({ type: "application/json" }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body.toString("utf8"), req.headers);
  } catch (err) {
    if (err instanceof WebhookVerificationError) return res.sendStatus(400);
    throw err;
  }

  // Responda primeiro. O processamento roda depois da resposta e nunca
  // deixa uma falha sem tratamento (uma rejeição solta derruba o Node).
  res.sendStatus(200);
  handleEvent(event).catch((err) => console.error("falha ao processar o evento", event.id, err));
});

app.listen(3000);
```

```python Python (Flask) theme={null}
# pip install standardwebhooks flask
import os
from flask import Flask, request
from standardwebhooks.webhooks import Webhook, WebhookVerificationError

app = Flask(__name__)
wh = Webhook(os.environ["UNITE_WEBHOOK_SECRET"])  # whsec_SEU_SEGREDO_AQUI

@app.post("/webhooks/unite")
def unite_webhook():
    try:
        # get_data() devolve o corpo cru, sem converter o JSON
        event = wh.verify(request.get_data(), dict(request.headers))
    except WebhookVerificationError:
        return "", 400

    # Responda rápido e entregue o evento à sua fila de tarefas
    enqueue(event)
    return "", 200
```

Isto só tira o processamento de dentro da resposta. Trabalho de verdade em segundo plano (gravar em banco, chamar outros sistemas, repetir em caso de erro) pertence à sua fila de tarefas: guarde o evento, devolva `200` e deixe um worker processar.

`verify` devolve o evento já convertido em objeto e lança `WebhookVerificationError` se a assinatura não bater ou se o `webhook-timestamp` for antigo demais. Responda `400` nesses casos.

### Sem a biblioteca

Se preferir não usar a biblioteca, a assinatura é calculada assim:

1. Tire o prefixo `whsec_` do segredo e decodifique o resto de base64. O resultado é a chave.
2. Monte o texto `webhook-id` + `.` + `webhook-timestamp` + `.` + corpo cru.
3. Calcule o HMAC-SHA256 desse texto com a chave e codifique em base64.
4. Compare com cada item de `webhook-signature` (separados por espaço, cada um no formato `v1,<base64>`), em tempo constante.
5. Rejeite a requisição se `webhook-timestamp` diferir do seu relógio em mais de 5 minutos.

```javascript theme={null}
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(secret, headers, rawBody) {
  const id = headers["webhook-id"];
  const timestamp = Number(headers["webhook-timestamp"]);
  const header = headers["webhook-signature"];
  if (typeof id !== "string" || typeof header !== "string") return false;
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key)
    .update(`${id}.${timestamp}.${rawBody}`)
    .digest();

  return header.split(" ").some((item) => {
    const [version, signature] = item.split(",");
    if (version !== "v1" || !signature) return false;
    const received = Buffer.from(signature, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}
```

A mesma conta em Python:

```python theme={null}
import base64
import hashlib
import hmac
import time

def verify(secret, headers, raw_body):
    headers = {k.lower(): v for k, v in headers.items()}  # nomes de cabeçalho não diferenciam maiúsculas
    msg_id = headers.get("webhook-id")
    header = headers.get("webhook-signature")
    try:
        timestamp = int(headers.get("webhook-timestamp"))
    except (TypeError, ValueError):
        return False
    if not msg_id or not header or abs(time.time() - timestamp) > 300:
        return False

    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body  # raw_body em bytes
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()

    for item in header.split(" "):
        version, _, signature = item.partition(",")
        if version == "v1" and signature and hmac.compare_digest(signature, expected):
            return True
    return False
```

Os nomes de cabeçalho não diferenciam maiúsculas de minúsculas (o Python acima os converte para minúsculas antes de ler). Nos dois exemplos, uma falha de formato (cabeçalho ausente ou fora do padrão) devolve `false`, nunca lança erro: responda `400`.

## Responder e processar

* Responda com `2xx` em até **10 segundos**. Passando disso, a tentativa conta como falha.
* Faça o mínimo antes de responder: confira a assinatura, guarde o evento e devolva `200`. Processe o resto em segundo plano.
* Redirecionamentos (`3xx`) **não** são seguidos e contam como falha. Cadastre o endereço final.
* A Unite não usa endereços de IP fixos para enviar. **Não** libere por IP: a verificação da assinatura é o que garante a origem.

## Novas tentativas

Qualquer resposta que não seja `2xx` (ou falta de resposta em 10 segundos) provoca uma nova tentativa. São até 12 tentativas por envio, com intervalo crescente de 30 segundos até 1 hora, ao longo de cerca de 5 a 6 horas. Se todas falharem, o envio fica como `failed`. Um envio que continue pendente por mais de 7 horas também aparece como `failed`, com `lastError` igual a `expired`.

A exceção é o status `410`: ele significa "este endereço não existe mais". Quando o seu destino responde `410`, a Unite **desativa o endpoint** (`status: "disabled"`, `disabledReason: "gone"`) e não tenta de novo. Outra exceção: se o endereço passar a resolver para um endereço privado ou bloqueado, o envio é encerrado sem nova tentativa, com `lastError` como `url_rejected:private_address`. Se o acesso à API for desligado no workspace, o envio também é encerrado sem nova tentativa, com `lastError` como `feature_disabled`. Um endpoint desativado não recebe mais eventos e não pode ser testado; crie outro para voltar a receber. Só responda `410` de propósito.

Um endpoint também é desativado sozinho, com `disabledReason: "creator_removed"`, quando quem o criou sai do workspace ou perde o acesso a ele. Ele deixa de receber eventos e não pode ser testado; um administrador cadastra outro endpoint. Revogar uma chave de API **não** afeta os endpoints: eles pertencem ao workspace, e os administradores os gerenciam no painel do workspace.

## Ordem e repetição

* **Não há garantia de ordem.** `pretest.report_ready` pode chegar antes de `pretest.completed`, e uma tentativa antiga pode chegar depois de uma mais nova.
* **Um evento pode chegar mais de uma vez.** Use o `webhook-id` para ignorar o que você já processou. Guarde os ids recebidos e descarte repetidos.
* **A verdade está no `GET`.** O evento avisa que algo mudou. Para o estado atual, consulte `GET /pretests/{id}`, e não confie na ordem de chegada.

```javascript theme={null}
const seen = new Set(); // em produção, use um banco com expiração

async function handleEvent(event) {
  if (seen.has(event.id)) return; // já processado
  seen.add(event.id);

  // consulte o estado atual em vez de confiar só no corpo do evento
  const res = await fetch(
    `https://myunite.ai/api/v1/pretests/${event.data.pretest.id}`,
    { headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` } },
  );
  const pretest = await res.json();
  // ...
}
```

## Testar o endpoint

`POST /webhook-endpoints/{id}/test` envia um evento `ping` assinado, igual aos demais. A resposta é `202`, com o id do envio e `status: "pending"`. O resultado aparece na lista de envios.

```bash curl theme={null}
curl -X POST https://myunite.ai/api/v1/webhook-endpoints/ID_DO_ENDPOINT/test \
  -H "Authorization: Bearer $UNITE_API_KEY"
```

```javascript JavaScript theme={null}
const res = await fetch(
  "https://myunite.ai/api/v1/webhook-endpoints/ID_DO_ENDPOINT/test",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` },
  },
);
console.log(res.status, await res.json()); // 202
```

```python Python theme={null}
import os
import requests

res = requests.post(
    "https://myunite.ai/api/v1/webhook-endpoints/ID_DO_ENDPOINT/test",
    headers={"Authorization": f"Bearer {os.environ['UNITE_API_KEY']}"},
)
print(res.status_code, res.json())  # 202
```

Um endpoint desativado não pode ser testado.

## Ler a lista de envios

`GET /webhook-endpoints/{id}/deliveries` devolve os últimos 50 envios daquele endpoint, do mais novo para o mais antigo.

```bash curl theme={null}
curl https://myunite.ai/api/v1/webhook-endpoints/ID_DO_ENDPOINT/deliveries \
  -H "Authorization: Bearer $UNITE_API_KEY"
```

```javascript JavaScript theme={null}
const res = await fetch(
  "https://myunite.ai/api/v1/webhook-endpoints/ID_DO_ENDPOINT/deliveries",
  { headers: { Authorization: `Bearer ${process.env.UNITE_API_KEY}` } },
);
const { data } = await res.json();
for (const d of data) {
  console.log(d.eventType, d.status, d.attempts, d.lastStatusCode, d.lastError);
}
```

```python Python theme={null}
import os
import requests

res = requests.get(
    "https://myunite.ai/api/v1/webhook-endpoints/ID_DO_ENDPOINT/deliveries",
    headers={"Authorization": f"Bearer {os.environ['UNITE_API_KEY']}"},
)
for d in res.json()["data"]:
    print(d["eventType"], d["status"], d["attempts"], d["lastStatusCode"], d["lastError"])
```

Cada item traz:

| Campo | Descrição |
| - | - |
| `id` | Id do envio. |
| `eventId` | Igual ao `webhook-id`. Use para cruzar com o que o seu servidor recebeu. |
| `eventType` | O tipo do evento, ou `ping` em um teste. |
| `status` | `pending` (ainda tentando), `delivered` ou `failed`. |
| `attempts` | Quantas tentativas já foram feitas. |
| `lastStatusCode` | Status HTTP da última tentativa. `null` se não houve resposta. |
| `lastError` | Motivo curto da última falha, por exemplo `timeout`, `http_500`, `redirect`, `expired`, `url_rejected:private_address` ou `feature_disabled`. `null` se não houve falha. |
| `createdAt` | Quando o envio foi criado. |
| `deliveredAt` | Quando foi entregue. `null` até lá. |

Se muitos envios aparecem como `failed`, confira se o seu servidor responde `2xx` em até 10 segundos, se o certificado é válido e se o endereço não redireciona.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.