> 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/atualizar-cadastro-webhook.md).

# Atualizar Cadastro de Webhook

Substitui completamente o cadastro de webhook do originator autenticado via JWT. Todos os campos do request substituem os valores anteriores. Use `POST` para criar quando ainda não existir cadastro (`404`).

{% 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 `PUT` é uma substituição total: `authValue` é **obrigatório** e substitui o secret anterior. Ele é **write-only** — nunca retornado em leituras nem na resposta deste `PUT`.
{% endhint %}

## Request

`PUT /api/v1/webhooks`

Autenticado: `Authorization: Bearer {originatorToken}`.

### Corpo

| Campo           | Tipo                                 | Obrigatório | Descrição                                                                                                |
| --------------- | ------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------- |
| `webhookUrls`   | `array` (1–20 itens)                 | Sim         | Nova lista de URLs HTTPS. Substitui a lista anterior. Mínimo 1, máximo 20.                               |
| `webhookUrls[]` | `string` (uri, `^https://`, max 500) | Sim         | URL HTTPS de entrega. Deve iniciar com `https://`.                                                       |
| `authKey`       | `string` (max 100)                   | Sim         | Novo nome do header HTTP de autenticação.                                                                |
| `authValue`     | `string` (write-only, max 500)       | Sim         | Novo valor secreto do header. **Write-only**: substitui o valor anterior e nunca é retornado em leitura. |
| `active`        | `boolean`                            | Sim         | Ativa ou desativa o cadastro. Um cadastro inativo não recebe entregas.                                   |

O originator recebe **todos** os tipos de evento automaticamente — não há seleção de eventos no cadastro. Veja o catálogo completo em [Eventos](https://docs.giro.tech/desenvolvedores/api-gtfgts/webhooks/eventos.md).

## 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 atualizado com sucesso. O campo `authValue` é omitido da resposta (write-only).

## Exemplo

```http
PUT /api/v1/webhooks HTTP/1.1
Host: ingress.gtfgts.staging.giro.tech
Authorization: Bearer {originatorToken}
Content-Type: application/json

{
  "webhookUrls": [
    "https://originator.example.com/callbacks/fgts",
    "https://originator.example.com/callbacks/fgts-backup"
  ],
  "authKey": "X-Webhook-Token",
  "authValue": "n3w-s3cr3t-t0k3n",
  "active": true
}
```

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

## Erros

| Código | Situação                                                                                                                            |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| 400    | Falha de Bean Validation (campos obrigatórios ausentes, URL não-HTTPS) — `errorCode = VALIDATION_ERROR`                             |
| 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).

## Atualiza o cadastro de webhook do originator autenticado

> Substitui completamente o cadastro de webhook do originator autenticado. Todos os campos do request substituem os valores anteriores.\
> O campo \`authValue\` é \*\*write-only\*\*: substituído pelo novo valor (obrigatório no \`PUT\`) e \*\*nunca\*\* retornado em leituras. Armazenado de forma segura.\
> \`404\` se o originator ainda não possui cadastro de webhook (use \`POST\` para criar).

```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":{"put":{"operationId":"updateWebhookSubscription","tags":["webhook-subscriptions"],"summary":"Atualiza o cadastro de webhook do originator autenticado","description":"Substitui completamente o cadastro de webhook do originator autenticado. Todos os campos do request substituem os valores anteriores.\nO campo `authValue` é **write-only**: substituído pelo novo valor (obrigatório no `PUT`) e **nunca** retornado em leituras. Armazenado de forma segura.\n`404` se o originator ainda não possui cadastro de webhook (use `POST` para criar).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Corpo para atualização completa do cadastro de webhook do originator autenticado. Substitui todos os campos do cadastro existente. O campo `authValue` é **write-only**: aceito nesta requisição, **nunca** retornado em leituras subsequentes (GET).","required":["webhookUrls","authKey","authValue","active"],"properties":{"webhookUrls":{"type":"array","minItems":1,"maxItems":20,"description":"Nova lista de URLs HTTPS para entrega de webhook. Substitui a lista anterior. Mínimo 1, máximo 20. Todas devem iniciar com `https://`.","items":{"type":"string","format":"uri","pattern":"^https://","minLength":1,"maxLength":500,"description":"URL HTTPS de entrega de webhook. Deve iniciar com `https://`."}},"authKey":{"type":"string","minLength":1,"maxLength":100,"description":"Novo nome do header HTTP de autenticação."},"authValue":{"type":"string","writeOnly":true,"minLength":1,"maxLength":500,"description":"Novo valor secreto do header de autenticação. **Write-only**: aceito no `POST`/`PUT`, **nunca** retornado em leitura (`GET`). Substitui o valor anterior."},"active":{"type":"boolean","description":"Ativa ou desativa o cadastro de webhook. Um cadastro inativo não recebe entregas."}}}}}},"responses":{"200":{"description":"Cadastro de webhook atualizado com sucesso. O campo `authValue` é omitido da resposta (write-only).","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)."}}}}}},"400":{"description":"Requisição inválida — falha de validação de Bean Validation (campos obrigatórios ausentes, formatos incorretos, CPF com dígitos errados, etc.). O campo `errors` contém um mapa `{ \"campo\": \"mensagem\" }` para cada campo inválido. O campo `title` é sempre `\"Bean validation error\"` e `detail` é sempre `\"One or more fields were invalid. See 'errors' for details.\"`.\nRejeições de regra de negócio também chegam como `400`, com `errorCode` próprio (ex.: `CONTRACT_INSTALLMENTS_MISMATCH`). Quando a rejeição aponta um campo do request, ela traz o mesmo `errors` e o mesmo `detail`; quando não há campo associado, `errors` é omitido e `detail` é o reason phrase do status.","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."}}}}}},"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/>" %}
