Gestão de Webhooks

A API permite cadastrar e gerenciar webhooks por unidade. Cada unidade pode ter 1 webhook ativo que recebe eventos como equipment.recognized.

Endpoints

Método	Rota	Scope	Descrição
GET	`/v1/webhooks`	`webhooks:read`	Listar webhooks da unidade
POST	`/v1/webhooks`	`webhooks:write`	Criar webhook (retorna `secret` uma vez)
GET	`/v1/webhooks/:id`	`webhooks:read`	Detalhar webhook
PUT	`/v1/webhooks/:id`	`webhooks:write`	Atualizar URL, eventos ou status
DELETE	`/v1/webhooks/:id`	`webhooks:write`	Desativar webhook (soft)
GET	`/v1/webhooks/:id/deliveries`	`webhooks:read`	Listar entregas (histórico)
POST	`/v1/webhooks/:id/test`	`webhooks:write`	Disparar evento de teste

GET /v1/webhooks

Lista o webhook da unidade atual (se existir).

Exemplo

curl "https://api.gdredu.com/v1/webhooks" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui"

Resposta (200)

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://minha-app.com/webhooks/gdredu",
      "events": ["equipment.recognized"],
      "isActive": true,
      "secretPrefix": "whsec_ab12cd34",
      "lastDeliveryAt": "2026-06-19T08:00:12.000Z",
      "lastStatus": 200,
      "createdAt": "2026-06-15T10:00:00.000Z",
      "updatedAt": "2026-06-19T08:00:12.000Z",
      "_count": { "deliveries": 42 }
    }
  ]
}

POST /v1/webhooks

Cria um novo webhook. O secret é gerado e retornado apenas nesta resposta.

Body

{
  "url": "https://minha-app.com/webhooks/gdredu",
  "events": ["equipment.recognized"],
  "isActive": true
}

Campo	Tipo	Obrigatório	Default	Descrição
`url`	string (URL)	sim	—	URL HTTPS que receberá os eventos
`events`	array	sim	—	Lista de eventos (atualmente apenas `equipment.recognized`)
`isActive`	boolean	não	`true`	Se o webhook está ativo

Exemplo

curl -X POST "https://api.gdredu.com/v1/webhooks" \
  -H "Authorization: Bearer gdredu_live_..." \
  -H "x-branch-id: branch-id-aqui" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "url": "https://minha-app.com/webhooks/gdredu",
    "events": ["equipment.recognized"]
  }'

Resposta (201)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
  "url": "https://minha-app.com/webhooks/gdredu",
  "events": ["equipment.recognized"],
  "isActive": true,
  "secretPrefix": "whsec_ab12cd34",
  "lastDeliveryAt": null,
  "lastStatus": null,
  "createdAt": "2026-06-19T12:00:00.000Z",
  "updatedAt": "2026-06-19T12:00:00.000Z",
  "secret": "whsec_ab12cd34ef5678901234567890abcdef1234567890abcdef1234567890abcdef"
}

:::danger[Armazene o secret com segurança]
O campo secret só é exibido nesta resposta. Guarde-o em um cofre de senhas. Se você perdê-lo, será necessário criar um novo webhook.
:::

Erros

Status	Code	Quando
409	`CONFLICT`	Já existe um webhook para esta unidade (1 por branch)

GET /v1/webhooks/:id

Retorna os detalhes de um webhook (sem o secret).

Resposta (200)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "branchId": "a999af34-c399-45f6-9dc9-5e8c024b0a49",
  "url": "https://minha-app.com/webhooks/gdredu",
  "events": ["equipment.recognized"],
  "isActive": true,
  "secretPrefix": "whsec_ab12cd34",
  "lastDeliveryAt": "2026-06-19T08:00:12.000Z",
  "lastStatus": 200,
  "createdAt": "2026-06-15T10:00:00.000Z",
  "updatedAt": "2026-06-19T08:00:12.000Z",
  "_count": { "deliveries": 42 }
}

PUT /v1/webhooks/:id

Atualiza URL, eventos ou status de um webhook. O secret não pode ser alterado por aqui — se precisar rotacionar, delete o webhook e crie um novo.

Body

Todos os campos são opcionais:

{
  "url": "https://nova-url.com/webhooks/gdredu",
  "events": ["equipment.recognized"],
  "isActive": true
}

DELETE /v1/webhooks/:id

Desativa o webhook. Pode ser reativado via PUT /v1/webhooks/:id com isActive: true.

Resposta (204)

Sem corpo.

GET /v1/webhooks/:id/deliveries

Lista o histórico de entregas do webhook (mais recentes primeiro).

Parâmetros (query)

Parâmetro	Tipo	Default	Descrição
`limit`	integer	`20`	Máximo 100

Resposta (200)

{
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "event": "equipment.recognized",
      "status": "SUCCESS",
      "attempt": 1,
      "nextAttemptAt": null,
      "responseStatus": 200,
      "responseError": null,
      "durationMs": 234,
      "deliveredAt": "2026-06-19T08:00:12.500Z",
      "ignoredAt": null,
      "createdAt": "2026-06-19T08:00:12.000Z"
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "event": "equipment.recognized",
      "status": "RETRYING",
      "attempt": 2,
      "nextAttemptAt": "2026-06-19T08:06:00.000Z",
      "responseStatus": 503,
      "responseError": "HTTP 503",
      "durationMs": 30000,
      "deliveredAt": null,
      "ignoredAt": null,
      "createdAt": "2026-06-19T08:00:12.000Z"
    }
  ]
}

POST /v1/webhooks/:id/test

Enfileira um evento de teste (com payload fixo) para validar a integração.

Resposta (202)

{
  "deliveryId": "880e8400-e29b-41d4-a716-446655440000",
  "message": "Evento de teste enfileirado para entrega."
}

O evento será entregue em segundos (se o receptor estiver saudável).

Conceitos importantes

1 webhook por unidade

Cada unidade pode ter no máximo 1 webhook ativo. Para "trocar" de webhook, desative o antigo e crie um novo (ou use PUT para atualizar).

Eventos disponíveis

Atualmente apenas equipment.recognized é emitido.