POST /api/webhooks

Cria um novo webhook para receber notificações de eventos em tempo real. O sistema enviará requisições HTTP POST ao URL configurado sempre que os eventos selecionados ocorrerem.

Autenticação

Scope necessário: webhooks:write

Inclua o header Authorization: Bearer <api-key> ou use cookie de sessão.

Requisição

POST /api/webhooks
Content-Type: application/json

Headers

Header	Obrigatório	Descrição
`Authorization`	sim	`Bearer pk_...` (API key) ou cookie de sessão
`Content-Type`	sim	`application/json`

Body

Campo	Tipo	Obrigatório	Padrão	Descrição
`name`	string	sim	—	Nome do webhook
`url`	string	sim	—	URL do endpoint que receberá os eventos (HTTPS recomendado)
`events`	string[]	sim	—	Lista de eventos a assinar
`secret`	string	não	auto-gerado	Secret para verificação HMAC-SHA256. Se vazio ou omitido, um secret seguro é gerado automaticamente
`enabled`	boolean	não	`true`	Webhook ativo
`headers`	object	não	`{}`	Headers HTTP customizados enviados com cada requisição

Eventos disponíveis

Evento	Descrição
`recognition.created`	Nova placa reconhecida por uma câmera
`alert.triggered`	Um alerta foi acionado por uma detecção
`camera.online`	Uma câmera ficou online (conectada ao agente)
`camera.offline`	Uma câmera ficou offline (desconectada do agente)

Exemplo

curl -X POST "https://api.placaflow.com.br/api/webhooks" \
  -H "Authorization: Bearer pk_a1b2c3d4e5f6g7h8i9j0..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sistema ERP",
    "url": "https://api.example.com/webhook/placaflow",
    "events": ["recognition.created", "alert.triggered"],
    "headers": {
      "Authorization": "Bearer meu-token-interno",
      "X-Source": "placaflow"
    }
  }'

Resposta 201

{
  "webhook": {
    "id": "w1b2c3d4-5678-9abc-def0-123456789abc",
    "userId": "c3a1e902-4f5b-4b8a-9c6d-1a2b3c4d5e6f",
    "createdAt": "2026-03-22T16:00:00.000Z",
    "updatedAt": "2026-03-22T16:00:00.000Z",
    "name": "Sistema ERP",
    "url": "https://api.example.com/webhook/placaflow",
    "secret": "whsec_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "enabled": true,
    "events": ["recognition.created", "alert.triggered"],
    "headers": {
      "Authorization": "Bearer meu-token-interno",
      "X-Source": "placaflow"
    },
    "lastDeliveryAt": null,
    "lastDeliveryStatus": null,
    "failureCount": 0
  }
}

Info

Se você não fornecer um secret, um será gerado automaticamente e retornado na resposta. Guarde esse valor para verificar a assinatura HMAC-SHA256 das requisições recebidas via header X-Signature-256.

Campos da resposta

Campo	Tipo	Descrição
`id`	string	UUID único do webhook
`userId`	string	UUID do proprietário
`createdAt`	string	Data de criação ISO 8601
`updatedAt`	string	Data da última atualização ISO 8601
`name`	string	Nome do webhook
`url`	string	URL do endpoint
`secret`	string	Secret para HMAC-SHA256 (auto-gerado se não fornecido)
`enabled`	boolean	Webhook ativo
`events`	string[]	Eventos assinados
`headers`	object	Headers HTTP customizados
`lastDeliveryAt`	string?	Sempre `null` na criação
`lastDeliveryStatus`	number?	Sempre `null` na criação
`failureCount`	number	Sempre `0` na criação

Erros

Código	Descrição
400	Campo `name`, `url` ou `events` obrigatório ausente ou dados inválidos
401	Não autenticado ou API key inválida
403	API key não possui scope `webhooks:write`