Autenticação do webhook (OAuth 2.0)

Por padrão, as chamadas de webhook são enviadas sem autenticação. Se o seu endereço de recebimento exige chamadas autenticadas, a API Jusbrasil Soluções suporta OAuth 2.0 no fluxo client credentials: antes de entregar os eventos, a API obtém um access_token no seu servidor de autenticação e envia cada chamada de webhook com o cabeçalho Authorization: Bearer <access_token>.

Como funciona

1. Você cadastra as credenciais do seu servidor de autenticação: token_url, client_id e client_secret.

2. Quando não há token válido em cache, a API faz um POST no token_url com grant_type=client_credentials no corpo e as credenciais em HTTP Basic (Authorization: Basic base64(client_id:client_secret)). O servidor de autenticação deve responder HTTP 200 com um JSON contendo o campo access_token.

3. A chamada de webhook é enviada com Authorization: Bearer <access_token>.

4. O token é reutilizado por até 55 minutos. O campo expires_in da resposta não é considerado: se o seu endereço de webhook responder 401 ou 403, a API descarta o token, obtém um novo e reenvia a chamada uma vez.

Se não for possível obter o token (resposta diferente de HTTP 200, resposta sem access_token ou servidor indisponível) ou se a chamada continuar recebendo 401 ou 403 com o token novo, a entrega é tratada como falha e segue a política de retentativas.

Nota

Somente o fluxo client credentials é suportado. O token_url deve ser um endereço HTTP ou HTTPS acessível pela internet, e redirecionamentos não são seguidos. O client_secret é armazenado de forma cifrada e nunca é retornado nas consultas à API.

Como configurar

Pela tela web: acesse o painel administrativo da empresa, seção Configuração da integração via API, bloco Autenticação do webhook (OAuth 2.0). Preencha Nome, Token URL, Client ID e Client Secret e clique em Salvar autenticação. A autenticação passa a valer para os endereços de webhook da empresa, inclusive os cadastrados depois.

Pela API, com o token de acesso de um usuário administrador da empresa:

curl -X POST 'https://op.digesto.com.br/api/webhook_auth_config' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "user_company_id": 12345,
    "auth_type_id": 1,
    "name": "OAuth do meu sistema",
    "active": true,
    "config_metadata": {
        "token_url": "https://auth.exemplo.com/oauth/token",
        "client_id": "meu-client-id",
        "client_secret": "meu-client-secret"
    }
}'

Campos do corpo:

Campo	Obrigatório	Descrição
user_company_id	Sim	ID da sua empresa. Não é preenchido automaticamente a partir do usuário autenticado.
auth_type_id	Sim	Tipo de autenticação. Use 1 (OAuth 2.0 client credentials). Os tipos disponíveis podem ser consultados em GET /api/webhook_auth_type.
name	Sim	Nome para identificar a configuração (até 100 caracteres).
active	Não	Se a configuração já entra em uso. Padrão true.
config_metadata	Sim	Credenciais do servidor de autenticação (tabela abaixo).

Campos de config_metadata:

Campo	Obrigatório	Descrição
token_url	Sim	Endpoint que emite o access_token (client credentials).
client_id	Sim	Identificador do cliente no servidor de autenticação.
client_secret	Sim	Segredo do cliente. Nunca é retornado em consultas.
token_request_client_type	Não	Como as credenciais são enviadas ao token_url: basic (HTTP Basic, padrão) ou headers (cabeçalhos Client-ID e Client-Secret).

Consultando a configuração

curl -X GET 'https://op.digesto.com.br/api/webhook_auth_config' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>'

A resposta lista as configurações da empresa, incluindo id, name, active, token_url, client_id e token_request_client_type. O client_secret não é retornado.

Regras

• Cada empresa pode ter uma única configuração de autenticação ativa. Para ativar outra, desative a atual antes.

• Para alterar as credenciais, informe token_url, client_id e client_secret juntos no PATCH.

• A desativação é feita via PATCH com "active": false; não há exclusão. Com a configuração desativada, as chamadas de webhook voltam a ser enviadas sem autenticação.

• Com a autenticação ativa, a requisição POST de teste feita ao cadastrar ou alterar um endereço de webhook aceita respostas 401 e 403 como prova de que o endereço está acessível, já que a chamada de teste não envia token.

Exemplo de atualização de credenciais:

curl -X PATCH 'https://op.digesto.com.br/api/webhook_auth_config/1' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "config_metadata": {
        "token_url": "https://auth.exemplo.com/oauth/token",
        "client_id": "meu-client-id",
        "client_secret": "meu-novo-client-secret"
    }
}'

Exemplo de desativação:

curl -X PATCH 'https://op.digesto.com.br/api/webhook_auth_config/1' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{"active": false}'