Webhooks
Receba notificações em tempo real sobre eventos importantes da plataforma através de webhooks.
Os webhooks são enviados como requisições POST HTTP para a URL configurada, com um payload JSON contendo os dados do evento.
Configuração
Para configurar webhooks, você precisa fornecer:
- URL de destino (endpoint HTTPS)
- Eventos que deseja receber
- Secret key para validação das requisições
Segurança
Cada requisição webhook inclui um header de assinatura para verificar a autenticidade:
X-BR-Dev-Signature: t=1678921234,v1=5257a869b4...Exemplo de como verificar a assinatura em Node.js:
const crypto = require('crypto');
const verifySignature = (payload, signature, secret) => {
const [timestamp, version] = signature.split(',');
const signedPayload = timestamp + '.' + JSON.stringify(payload);
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(version),
Buffer.from('v1=' + expectedSignature)
);
};Eventos Disponíveis
| Tipo de Evento | Descrição | Payload |
|---|---|---|
| project.created | Quando um novo projeto é criado | {
"id": "string",
"name": "string",
"description": "string",
"clientId": "string",
"status": "string",
"createdAt": "datetime"
} |
| project.updated | Quando um projeto é atualizado | {
"id": "string",
"name": "string",
"description": "string",
"status": "string",
"updatedAt": "datetime"
} |
| task.completed | Quando uma tarefa é marcada como concluída | {
"id": "string",
"projectId": "string",
"title": "string",
"completedAt": "datetime",
"completedBy": {
"id": "string",
"name": "string"
}
} |
| client.created | Quando um novo cliente é cadastrado | {
"id": "string",
"name": "string",
"email": "string",
"createdAt": "datetime"
} |
Boas Práticas
- Implemente retry com backoff exponencial para falhas
- Processe eventos de forma idempotente
- Responda rapidamente (2xx) e processe de forma assíncrona
- Monitore falhas e configure alertas
- Mantenha logs detalhados das requisições
Sempre valide a assinatura dos webhooks antes de processar os eventos para garantir a segurança.