Pular para o conteúdo
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Configuração via API

O originator cadastra, consulta, atualiza e remove sua subscription de webhook pela API REST do ingress, usando o token JWT de origem. A subscription define para onde entregar (webhookUrls) e como autenticar (authKey/authValue). O originator recebe todos os tipos de evento automaticamente — não há seleção de eventos.

Base path: /api/v1/webhooks

Cada originator possui no máximo uma subscription (relação 1:1). Para atualizar, use PUT. Ao concluir cada operação, a plataforma envia um POST para cada URL cadastrada, com retry e back-off exponencial em caso de falha — ver Retry e Garantias de Entrega.

O campo authValue é write-only: aceito no POST/PUT, mas nunca retornado em leituras (GET). É persistido cifrado/como secret.


Campos da subscription

Campo
Tipo
Obrigatório
Descrição

webhookUrls

array<string>

Sim

Lista de URLs HTTPS de entrega. Mínimo 1, máximo 20. Todas devem iniciar com https:// (máx. 500 caracteres cada). O mesmo evento é entregue para todas as URLs configuradas.

authKey

string

Sim

Nome do header HTTP de autenticação enviado em cada entrega (ex.: X-Webhook-Token). 1–100 caracteres.

authValue

string (write-only)

Sim

Valor secreto do header de autenticação. Aceito no POST/PUT, nunca retornado em GET. 1–500 caracteres. Definido por você e mantido em segredo.

active

boolean

Sim (no PUT)

Indica se a subscription está ativa e receberá entregas. Enviado no PUT e retornado nas leituras.

A resposta da API (201 na criação, 200 na consulta) inclui campos gerados pelo servidor que não fazem parte do corpo de entrada: id (identificador interno da subscription) e createdDate (timestamp ISO-8601 da criação) são read-only — nunca enviados nas requisições. O campo active é retornado nas leituras e nasce true na criação: não o envie no POST (a subscription é criada sempre ativa), mas envie-o no PUT para ativar ou desativar a subscription.

O originator recebe todos os tipos de evento automaticamente — não há seleção nem filtro de eventos na subscription. Veja o catálogo completo de eventType entregues em Eventos.


Endpoints (CRUD)

O ciclo completo de gerenciamento da subscription está na API Reference:

Operação
Endpoint
Referência

Criar

POST /api/v1/webhooks

Consultar

GET /api/v1/webhooks

Atualizar

PUT /api/v1/webhooks

Remover

DELETE /api/v1/webhooks


Exemplo — criar subscription

A resposta 201 ecoa a subscription sem o authValue (write-only):


authKey e authValue

Campo
Descrição

authKey

Nome do header HTTP que o GTFgts envia em cada POST para as suas URLs (ex.: X-Webhook-Token, Authorization).

authValue

Valor desse header. Configurado por você e enviado em todas as chamadas de entrega. Write-only — não é retornado em GET.

Valide sempre o header no seu endpoint antes de processar o payload. Detalhes do modelo de autenticação e exemplos de receptores em Segurança e Exemplos.

Atualizado