Endpoints da API

Autenticacao

Todos os endpoints da API publica (/api/v1/webhooks) exigem o header Idempotency-Key com um UUID valido em requisicoes POST e PUT. Isso garante que requisicoes duplicadas sejam tratadas de forma segura.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

A chave de idempotencia expira em 24 horas. Requisicoes com a mesma chave e mesmo body retornam a resposta cacheada. Requisicoes com a mesma chave mas body diferente retornam 409 Conflict.

Criar webhook

POST /api/v1/webhooks

Request

{
  "nome": "meu-webhook-pix",
  "url": "https://meu-servico.com/webhook",
  "tipo": "ATUALIZACAO_STATUS_PIX",
  "secret": "minha-chave-secreta-com-pelo-menos-32-caracteres",
  "ativo": true
}

Campo	Tipo	Obrigatorio	Validacao
`nome`	string	sim	Max 100 caracteres
`url`	string	sim	HTTPS, IP publico, max 500 caracteres
`tipo`	enum	sim	`ATUALIZACAO_STATUS_PIX` ou `FALHA_WEBHOOK`
`secret`	string	sim	Min 32, max 500 caracteres
`ativo`	boolean	nao	Default: `true`

Response `201 Created`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nome": "meu-webhook-pix",
  "url": "https://meu-servico.com/webhook",
  "tipo": "ATUALIZACAO_STATUS_PIX",
  "ativo": true,
  "criadoEm": "2026-05-01T12:00:00",
  "atualizadoEm": "2026-05-01T12:00:00"
}

Erros

Status	Codigo	Causa
`400`	`VALIDATION_ERROR`	Campos invalidos
`409`	`DUPLICATE_URL`	URL ja registrada em outro webhook
`409`	`DUPLICATE_IDEMPOTENCY_KEY`	Mesma chave de idempotencia com body diferente
`422`	`INVALID_URL`	URL nao e HTTPS ou resolve para IP privado

Listar webhooks

GET /api/v1/webhooks

Query parameters

Parametro	Tipo	Obrigatorio	Descricao
`tipo`	enum	nao	Filtrar por tipo: `ATUALIZACAO_STATUS_PIX` ou `FALHA_WEBHOOK`
`ativo`	boolean	nao	Filtrar por status ativo/inativo
`page`	int	nao	Pagina (default: `0`)
`size`	int	nao	Itens por pagina (1-100, default: `50`)

Response `200 OK`

Retorna um objeto paginado do Spring com a lista de webhooks no campo content.

{
  "content": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "nome": "meu-webhook-pix",
      "url": "https://meu-servico.com/webhook",
      "tipo": "ATUALIZACAO_STATUS_PIX",
      "ativo": true,
      "criadoEm": "2026-05-01T12:00:00",
      "atualizadoEm": "2026-05-01T12:00:00"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 50
}

Buscar webhook por ID

GET /api/v1/webhooks/{id}

Response `200 OK`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "nome": "meu-webhook-pix",
  "url": "https://meu-servico.com/webhook",
  "tipo": "ATUALIZACAO_STATUS_PIX",
  "ativo": true,
  "criadoEm": "2026-05-01T12:00:00",
  "atualizadoEm": "2026-05-01T12:00:00"
}

Erros

Status	Codigo	Causa
`404`	`NOT_FOUND`	Webhook nao encontrado

Atualizar webhook

PUT /api/v1/webhooks/{id}

Atualizacao parcial — envie apenas os campos que deseja alterar.

Request

{
  "nome": "novo-nome",
  "url": "https://novo-endpoint.com/webhook",
  "secret": "nova-chave-secreta-com-pelo-menos-32-caracteres",
  "ativo": false
}

Campo	Tipo	Obrigatorio	Validacao
`nome`	string	nao	Max 100 caracteres
`url`	string	nao	HTTPS, IP publico, max 500 caracteres
`secret`	string	nao	Min 32, max 500 caracteres
`ativo`	boolean	nao	—

O campo tipo nao pode ser alterado apos a criacao.

Response `200 OK`

Retorna o webhook atualizado no mesmo formato de WebhookResponse.

Excluir webhook

DELETE /api/v1/webhooks/{id}

Exclusao logica (soft delete). O webhook nao recebera mais eventos, mas seus registros de entrega sao mantidos.

Response `204 No Content`

Listar entregas de um webhook

GET /api/v1/webhooks/{id}/entregas

Query parameters

Parametro	Tipo	Obrigatorio	Descricao
`status`	enum	nao	`SUCESSO`, `FALHA` ou `AGUARDANDO_RETENTATIVA`
`page`	int	nao	Pagina (default: `0`)
`size`	int	nao	Itens por pagina (1-100, default: `50`)

Response `200 OK`

{
  "content": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "webhookId": "550e8400-e29b-41d4-a716-446655440000",
      "eventoId": "770e8400-e29b-41d4-a716-446655440002",
      "status": "SUCESSO",
      "tentativas": 1,
      "httpStatus": 200,
      "responseBody": "{\"ok\":true}",
      "payloadEnviado": [
        {
          "numeroDocumento": "12345678901",
          "status": "SETTLED",
          "valor": 15000,
          "end2end": "E12345678202301011200abcdef12345",
          "razaoRejeicao": null
        }
      ],
      "tentadoEm": "2026-05-01T12:00:00",
      "proximaTentativaEm": null
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "number": 0,
  "size": 50
}

Retentar entrega

POST /api/v1/webhooks/{id}/entregas/{entregaId}/retry

Cria uma nova tentativa de entrega para uma entrega com status FALHA.

Response `202 Accepted`

Retorna um novo WebhookEntregaResponse com a nova tentativa de entrega.

Respostas de erro

Todas as respostas de erro seguem o formato:

{
  "codigo": "VALIDATION_ERROR",
  "mensagem": "Falha de validacao",
  "detalhes": [
    { "campo": "url", "erro": "must not be blank" }
  ],
  "traceId": "abc123def456",
  "timestamp": "2026-05-01T12:00:00Z"
}

Campo	Tipo	Descricao
`codigo`	string	Codigo do erro
`mensagem`	string	Mensagem legivel
`detalhes`	array	Lista de erros de campo (apenas em erros de validacao)
`traceId`	string	ID de rastreamento OpenTelemetry
`timestamp`	string	Timestamp ISO-8601

Endpoints da API

On this page