API
Webhooks
Receba notificações em tempo real sobre eventos na plataforma Nobur.
Webhooks
Webhooks permitem que seu sistema receba notificações automáticas quando eventos ocorrem na plataforma Nobur. Em vez de consultar a API periodicamente (polling), seu endpoint recebe uma requisição HTTP POST em tempo real.
Como Funciona
- Você registra uma URL de endpoint e os eventos desejados
- Quando um evento ocorre, o Nobur envia um POST para sua URL
- Seu endpoint retorna
2xxpara confirmar o recebimento - Se a entrega falhar, o Nobur tenta novamente com backoff exponencial
Eventos Disponíveis
| Evento | Descrição |
|---|---|
broker.created | Corretor criado |
broker.updated | Corretor atualizado |
broker.deleted | Corretor excluído |
property.created | Imóvel criado |
property.updated | Imóvel atualizado |
property.deleted | Imóvel excluído |
party.created | Parte criada |
party.updated | Parte atualizada |
party.deleted | Parte excluída |
proposal.created | Proposta criada |
proposal.updated | Proposta atualizada |
proposal.deleted | Proposta excluída |
contract.created | Contrato criado |
contract.updated | Contrato atualizado |
contract.deleted | Contrato excluído |
document.created | Documento criado |
document.updated | Documento atualizado |
document.deleted | Documento excluído |
Registrando um Webhook
curl -X POST https://api.nobur.com.br/public/v1/webhooks \
-H "X-API-Key: nbr_sua_chave_aqui" \
-H "Content-Type: application/json" \
-d '{
"url": "https://meuapp.com/webhooks/nobur",
"events": ["broker.created", "broker.updated", "property.created"]
}'Resposta (201):
{
"id": "whs_abc123",
"url": "https://meuapp.com/webhooks/nobur",
"events": ["broker.created", "broker.updated", "property.created"],
"secret": "whsec_...",
"is_active": true,
"created_at": "2026-02-15T12:00:00Z",
"updated_at": "2026-02-15T12:00:00Z"
}O campo secret é retornado apenas na criação. Guarde-o em local seguro para verificar assinaturas.
Formato do Payload
Cada entrega contém um payload JSON com as informações do evento:
{
"id": "whd_abc123",
"event_type": "broker.created",
"created_at": "2026-02-15T12:00:00Z",
"payload": {
"id": "brk_abc123",
"name": "João da Silva",
"creci": "12345-F",
"email": "joao@imobiliaria.com",
"tenant_id": "tnt_abc123",
"organization_id": "org_abc123",
"created_at": "2026-02-15T12:00:00Z",
"updated_at": "2026-02-15T12:00:00Z"
}
}Verificação de Assinatura
Cada entrega inclui o header X-Webhook-Signature com uma assinatura HMAC-SHA256 do corpo da requisição, usando o secret do webhook como chave.
Verifique sempre a assinatura para garantir que a requisição veio do Nobur.
Exemplo em Node.js
const crypto = require("crypto");
function verifyWebhookSignature(body, signature, secret) {
const expectedSignature = "sha256=" + crypto
.createHmac("sha256", secret)
.update(body, "utf8")
.digest("hex");
if (signature.length !== expectedSignature.length) {
return false;
}
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// No handler do webhook
app.post("/webhooks/nobur", (req, res) => {
const signature = req.headers["x-webhook-signature"];
const body = req.rawBody; // corpo da requisição como string
if (!verifyWebhookSignature(body, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).send("Assinatura inválida");
}
const event = JSON.parse(body);
console.log(`Evento recebido: ${event.event_type}`);
// Processar o evento
switch (event.event_type) {
case "broker.created":
// Criar corretor no seu sistema
break;
case "property.updated":
// Atualizar imóvel no seu sistema
break;
}
res.status(200).send("OK");
});Exemplo em Python
import hmac
import hashlib
def verify_webhook_signature(body: bytes, signature: str, secret: str) -> bool:
expected = "sha256=" + hmac.new(
secret.encode("utf-8"),
body,
hashlib.sha256
).hexdigest()
return hmac.compare_digest(signature, expected)
# No handler do webhook (Flask)
@app.route("/webhooks/nobur", methods=["POST"])
def handle_webhook():
signature = request.headers.get("X-Webhook-Signature")
body = request.get_data()
if not verify_webhook_signature(body, signature, WEBHOOK_SECRET):
return "Assinatura inválida", 401
event = request.get_json()
print(f"Evento recebido: {event['event_type']}")
# Processar o evento
if event["event_type"] == "broker.created":
# Criar corretor no seu sistema
pass
return "OK", 200Retentativas
Se a entrega falhar (timeout ou status HTTP diferente de 2xx), o Nobur tenta novamente com backoff exponencial:
| Tentativa | Intervalo aproximado |
|---|---|
| 1a | imediata |
| 2a | 1 minuto |
| 3a | 5 minutos |
| 4a | 30 minutos |
| 5a | 2 horas |
Após 5 tentativas sem sucesso, a entrega é marcada como failed.
Consultando Entregas
Você pode consultar o histórico de entregas de um webhook:
curl -X GET "https://api.nobur.com.br/public/v1/webhooks/whs_abc123/deliveries?limit=10" \
-H "X-API-Key: nbr_sua_chave_aqui"Resposta:
{
"items": [
{
"id": "whd_abc123",
"subscription_id": "whs_abc123",
"event_type": "broker.created",
"status": "success",
"http_status": 200,
"attempt_count": 1,
"created_at": "2026-02-15T12:00:00Z",
"completed_at": "2026-02-15T12:00:01Z"
}
],
"page_info": {
"has_next_page": false,
"has_previous_page": false
}
}Status de Entrega
| Status | Descrição |
|---|---|
pending | Entrega aguardando envio ou retentativa |
success | Entrega concluída com sucesso (resposta 2xx) |
failed | Todas as tentativas falharam |
Boas Práticas
- Responda rapidamente -- retorne
200o mais rápido possível e processe o evento de forma assíncrona - Implemente idempotência -- seu endpoint pode receber o mesmo evento mais de uma vez; use o
idda entrega para deduplicação - Verifique a assinatura -- sempre valide o header
X-Webhook-Signatureantes de processar - Use HTTPS -- a URL do webhook deve usar HTTPS em produção
- Monitore falhas -- consulte o endpoint de entregas para identificar problemas