> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtfgts/api-reference/cadastro-webhook/obter-cadastro-webhook.md).

# Obter Cadastro de Webhook

Retorna o cadastro de webhook ativo do originator autenticado via JWT. Não há `id` na rota — o cadastro é único por originator, identificado pelo claim do token.

{% hint style="info" %}
Para o ciclo de vida da entrega, o catálogo de eventos entregues e a validação de assinatura, veja [Configuração via API](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/configuracao-via-api.md), [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md), [Payloads](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/payloads.md) e [Segurança e exemplos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/seguranca-e-exemplos.md).
{% endhint %}

{% hint style="warning" %}
O campo `authValue` é um secret **write-only** e **nunca** é retornado nesta leitura. Apenas o `authKey` (nome do header) aparece na resposta.
{% endhint %}

## Request

`GET /api/v1/webhooks`

Autenticado: `Authorization: Bearer {originatorToken}`.

## Response

| Campo         | Tipo                 | Descrição                                                                                         |
| ------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| `id`          | `integer` (int64)    | Identificador do cadastro de webhook                                                              |
| `webhookUrls` | `array`              | Lista de URLs HTTPS configuradas para entrega                                                     |
| `authKey`     | `string`             | Nome do header HTTP de autenticação. O `authValue` correspondente é write-only e não é retornado. |
| `active`      | `boolean`            | Indica se o cadastro está ativo e receberá entregas                                               |
| `createdDate` | `string` (date-time) | Data e hora de criação do cadastro (ISO-8601 UTC)                                                 |

* **200 OK** — cadastro de webhook retornado com sucesso. O campo `authValue` é omitido (write-only).

## Exemplo

```http
GET /api/v1/webhooks HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
```

```json
{
  "id": 42,
  "webhookUrls": [
    "https://originator.example.com/callbacks/fgts"
  ],
  "authKey": "X-Webhook-Token",
  "active": true,
  "createdDate": "2026-06-14T10:00:00Z"
}
```

## Erros

| Código | Situação                                                                                                                            |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| 401    | Token ausente, inválido ou expirado — `errorCode = UNAUTHORIZED`                                                                    |
| 404    | O originator autenticado ainda não possui cadastro de webhook. Use `POST` para criar — `errorCode = WEBHOOK_SUBSCRIPTION_NOT_FOUND` |
| 500    | Erro interno inesperado — `errorCode = INTERNAL_ERROR`                                                                              |
| 503    | Indisponibilidade momentânea — `errorCode = SUBMISSION_TEMPORARILY_UNAVAILABLE` (header `Retry-After: 5`)                           |

Os erros seguem o formato `ProblemDetail` (RFC 7807), com o campo `errorCode`. Ver [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtfgts/guias/erros.md).

## Obtém o cadastro de webhook do originator autenticado

> Retorna o cadastro de webhook ativo do originator autenticado. O campo \`authValue\` \*\*nunca\*\* é retornado (write-only).\
> \`404\` se o originator ainda não possui cadastro de webhook.

```json
{"openapi":"3.0.3","info":{"title":"gtfgts-ingress Public API","version":"0.0.1"},"tags":[{"name":"webhook-subscriptions","description":"CRUD de cadastro de webhook escopado ao originator autenticado. O originator define as URLs de entrega e as credenciais de autenticação via os campos `webhookUrls`, `authKey` e `authValue`. Não há seleção por evento: todos os eventos são entregues automaticamente ao cadastro ativo."}],"servers":[{"url":"https://ingress.gtfgts.staging.giro.tech","description":"Homologação (testes e validação da integração)"},{"url":"https://gtfgts.giro.tech","description":"Produção (operações reais)"},{"url":"http://localhost:8080","description":"Local (bootRun -Pprofiles=local)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT de originator fornecido pela GTLab no cadastro do originator. Identifica e autoriza o originator em todos os endpoints `/api/v1/**`.\nInclua no header: `Authorization: Bearer <token>`."}}},"paths":{"/api/v1/webhooks":{"get":{"operationId":"getWebhookSubscription","tags":["webhook-subscriptions"],"summary":"Obtém o cadastro de webhook do originator autenticado","description":"Retorna o cadastro de webhook ativo do originator autenticado. O campo `authValue` **nunca** é retornado (write-only).\n`404` se o originator ainda não possui cadastro de webhook.","responses":{"200":{"description":"Cadastro de webhook do originator. O campo `authValue` é omitido (write-only — nunca retornado em leitura).","content":{"application/json":{"schema":{"type":"object","description":"Cadastro de webhook do originator autenticado. O campo `authValue` é **sempre omitido** nesta resposta — é um secret write-only que nunca é retornado em leituras (GET/POST response/PUT response).","properties":{"id":{"type":"integer","format":"int64","description":"Identificador interno do cadastro de webhook."},"webhookUrls":{"type":"array","items":{"type":"string","format":"uri"},"description":"Lista de URLs HTTPS configuradas para entrega de webhook."},"authKey":{"type":"string","description":"Nome do header HTTP de autenticação enviado nas chamadas de entrega. O valor correspondente (`authValue`) é write-only e não é retornado."},"active":{"type":"boolean","description":"Indica se o cadastro de webhook está ativo e receberá entregas."},"createdDate":{"type":"string","format":"date-time","description":"Data e hora de criação do cadastro (ISO-8601 UTC)."}}}}}},"401":{"description":"Não autenticado — JWT ausente, inválido ou expirado. Autentique-se e inclua o token no header `Authorization: Bearer <token>`.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"404":{"description":"Cadastro de webhook não encontrado — o originator autenticado ainda não possui um cadastro. Use `POST /api/v1/webhooks` para criar.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}},"500":{"description":"Erro interno inesperado no servidor.","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro estruturado segundo RFC 7807 — Problem Details for HTTP APIs. Campos adicionais `errorCode` (código canônico GTLab estável) e `timestamp` (instante do erro no servidor) são extensões proprietárias. O campo `errors` (mapa campo→mensagem) é incluído nos erros que apontam para um campo do request: validação de Bean Validation (`errorCode: VALIDATION_ERROR`, HTTP 400) e rejeições de regra de negócio que identificam o campo culpado (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Nos erros que não têm campo associado (`401`, `403`, `404`, `429`, `500`, `503`, e rejeições de negócio sem campo) o campo `errors` está ausente.","properties":{"type":{"type":"string","format":"uri","description":"URI de referência do tipo de problema."},"title":{"type":"string","description":"Título legível do tipo de problema."},"status":{"type":"integer","format":"int32","description":"HTTP status code do problema."},"detail":{"type":"string","description":"Descrição legível específica desta ocorrência do problema."},"instance":{"type":"string","description":"URI reference (relativa ou absoluta) que identifica esta ocorrência específica do problema. Geralmente o path do endpoint que gerou o erro."},"errorCode":{"type":"string","description":"Código de erro canônico GTLab estável para uso programático."},"timestamp":{"type":"string","format":"date-time","description":"Instante em que o erro ocorreu no servidor (ISO-8601 UTC)."},"errors":{"type":"object","nullable":true,"additionalProperties":{"type":"string"},"description":"Mapa de erros no formato `{ \"campo\": \"mensagem\" }`, onde cada chave nomeia um campo do **request enviado por você**. Presente quando `errorCode` é `VALIDATION_ERROR` (falha de Bean Validation — `@NotBlank`, `@NotNull`, `@Size`, `@Pattern`, etc.) e também em rejeições de regra de negócio que conseguem apontar o campo culpado, como `CONTRACT_INSTALLMENTS_MISMATCH`. Quando presente, `detail` é `\"One or more fields were invalid. See 'errors' for details.\"`. Ausente em erros sem campo associado (`401`, `403`, `404`, `429`, `500`, `503`) e em rejeições de negócio que não se referem a um campo do request."}}}}}}}}}}}
```

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
