Visão geral de Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real quando eventos acontecem na GDREdu, sem precisar ficar consultando (polling) a API.

Cada unidade pode ter 1 webhook registrado, que recebe todos os eventos habilitados para aquela unidade.

Eventos disponíveis

Evento	Descrição
`equipment.recognized`	Disparado quando um equipamento reconhece um estudante ou responsável entrando ou saindo da escola.

Como funciona

sequenceDiagram
    participant E as Equipamento
    participant API as API GDREdu
    participant R as Sua URL

    E->>API: Reconhece pessoa (entrada/saída)
    API-->>E: Confirma o reconhecimento

    API->>R: POST com payload + assinatura HMAC
    R-->>API: 200 OK (em até 30s)

    alt Falha (não-2xx ou timeout)
        API->>R: Reagenda tentativa (1m, 5m, 10m, 1h, 6h)
    end

Configurar um webhook

Crie a URL receptora na sua aplicação que vai receber os POSTs
Valide a assinatura HMAC (veja Assinatura HMAC)
Responda rapidamente (≤ 30s) com status 2xx
Cadastre a URL via POST /v1/webhooks ou pelo painel administrativo em Gestão → Webhooks (veja o Guia do Administrador — Webhooks)
Guarde o secret retornado — ele não será mostrado novamente
Teste com POST /v1/webhooks/:id/test ou pelo botão de teste no painel

Garantias de entrega

Pelo menos uma vez: o evento é entregue 1 vez ou mais. Em caso de falha, retentativas automáticas.
Backoff: 1min, 5min, 10min, 1h, 6h (5 retentativas no total).
Timeout: 30 segundos por tentativa.
Status final: após 6 tentativas sem sucesso, o evento é marcado como IGNORED.
Desduplicação: o header X-GDREdu-Delivery-Id é único por entrega; use-o se precisar idempotar.

Limites

1 webhook por unidade
O histórico de entregas está disponível via GET /v1/webhooks/:id/deliveries

Próximos passos

Assinatura HMAC — Como verificar a autenticidade dos eventos
equipment.recognized — Detalhes do payload
Retentativas — Política de retry em detalhes
Exemplo de receptor — Código completo em Node.js