Webhooks

Recebe notificações em tempo real quando os dados se alteram. O Brutlers envia pedidos HTTP POST para a tua URL registada.

Configurar webhook

Regista uma URL que consiga receber pedidos HTTP POST. Receberás um secret para verificação de assinatura.

POST

/api/vendor/webhooks

Regista um novo webhook. O secret é mostrado apenas uma vez.

bash

curl -X POST https://brutlers.com/api/vendor/webhooks \
  -H "X-Api-Key: brut_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meine-app.de/webhooks/brutlers",
    "events": ["order.created", "order.status_changed"]
  }'

Máximo de 5 webhooks por fornecedor

Eventos disponíveis

Event	Description
order.created	Nova encomenda criada
order.status_changed	Estado da encomenda alterado
inquiry.received	Novo pedido de informação recebido
appointment.confirmed	Marcação confirmada
appointment.cancelled	Marcação cancelada
customer.created	Novo cliente criado

Formato do payload

Cada pedido webhook contém um corpo JSON com o tipo de evento e os dados correspondentes.

json

{
  "event": "order.status_changed",
  "data": {
    "id": "clx1234567890abcdef",
    "status": "FITTING_READY",
    "previousStatus": "IN_PRODUCTION",
    "customerId": "clx0987654321fedcba",
    "updatedAt": "2026-04-15T10:00:00.000Z"
  },
  "timestamp": "2026-04-15T10:00:01.234Z"
}

Verificação de assinatura

Cada pedido contém um cabeçalho de assinatura HMAC-SHA256. Verifica a assinatura para garantir que o pedido provém do Brutlers.

Header

X-Brutlers-Signature

javascript

import { createHmac } from "crypto";

function verifySignature(body, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return signature === expected;
}

// Express/Next.js example
app.post("/webhooks/brutlers", (req, res) => {
  const signature = req.headers["x-brutlers-signature"];
  const body = JSON.stringify(req.body);

  if (!verifySignature(body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = req.body;
  console.log(`Event: ${event}`, data);
  res.status(200).send("OK");
});

Política de retry

Em caso de erros (estado ≠ 2xx ou timeout), o webhook é repetido até 3 vezes:

11.ª tentativa: após 1 minuto
22.ª tentativa: após 5 minutos
33.ª tentativa: após 30 minutos

Gestão de webhooks

GET

/api/vendor/webhooks

Regista um novo webhook. O secret é mostrado apenas uma vez.

PUT

/api/vendor/webhooks/:id

Atualiza o URL, eventos ou estado de um webhook.

DELETE

/api/vendor/webhooks/:id

Elimina um webhook e todos os registos de entrega associados.

Configurar webhook

Regista uma URL que consiga receber pedidos HTTP POST. Receberás um secret para verificação de assinatura.

POST

/api/vendor/webhooks

Regista um novo webhook. O secret é mostrado apenas uma vez.

bash

curl -X POST https://brutlers.com/api/vendor/webhooks \
  -H "X-Api-Key: brut_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meine-app.de/webhooks/brutlers",
    "events": ["order.created", "order.status_changed"]
  }'

Máximo de 5 webhooks por fornecedor

Event

Description

order.created

Nova encomenda criada

order.status_changed

Estado da encomenda alterado

inquiry.received

Novo pedido de informação recebido

appointment.confirmed

Marcação confirmada

appointment.cancelled

Marcação cancelada

customer.created

Novo cliente criado

Formato do payload

Cada pedido webhook contém um corpo JSON com o tipo de evento e os dados correspondentes.

json

{
  "event": "order.status_changed",
  "data": {
    "id": "clx1234567890abcdef",
    "status": "FITTING_READY",
    "previousStatus": "IN_PRODUCTION",
    "customerId": "clx0987654321fedcba",
    "updatedAt": "2026-04-15T10:00:00.000Z"
  },
  "timestamp": "2026-04-15T10:00:01.234Z"
}

Verificação de assinatura

Cada pedido contém um cabeçalho de assinatura HMAC-SHA256. Verifica a assinatura para garantir que o pedido provém do Brutlers.

Header

X-Brutlers-Signature

javascript

import { createHmac } from "crypto";

function verifySignature(body, signature, secret) {
  const expected = createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return signature === expected;
}

// Express/Next.js example
app.post("/webhooks/brutlers", (req, res) => {
  const signature = req.headers["x-brutlers-signature"];
  const body = JSON.stringify(req.body);

  if (!verifySignature(body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send("Invalid signature");
  }

  const { event, data } = req.body;
  console.log(`Event: ${event}`, data);
  res.status(200).send("OK");
});