Criar Webhook

curl --location 'https://gyra-core.gyramais.com.br/webhook' \
--header 'Authorization: Bearer {seu_token_jwt}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx"
}'

fetch("https://gyra-core.gyramais.com.br/webhook", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {seu_token_jwt}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx"
})
})
  .then(res => res.json())
  .then(console.log)

import requests

url = "https://gyra-core.gyramais.com.br/webhook"
headers = {
  "Authorization": "Bearer {seu_token_jwt}"
}
payload = {
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

{
  "id": "69a20f96f5b9cb55d8e8a6a1",
  "organizationId": "65eb4989a4a87b9a94d1920f",
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx",
  "createdAt": "2026-02-27T21:41:42.013Z",
  "updatedAt": "2026-02-27T21:41:42.013Z"
}

{
  "code": 400,
  "message": "type must be one of the following values: REPORT, OPTIN, CREDIT_POLICY, REPORT_STATUS, REPORT_FINISHED, REPORT_EXPORTED, OPERATION,type should not be empty,url should not be empty,url must be a string"
}

{
  "code": 401,
  "message": "Token de acesso inválido."
}

Quando usar

Use este endpoint para cadastrar um destino de webhook e receber eventos da plataforma em tempo real. Você pode usar quando quiser reagir automaticamente a mudanças de status de relatório, conclusão de processamento ou eventos operacionais sem depender de polling.

Autenticação

Bearer JWT no header Authorization.

Corpo da requisição

{
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx"
}

type (obrigatório): um dos tipos de webhook abaixo. Cada webhook escuta um único tipo; para receber mais de um, cadastre webhooks separados.
url (obrigatório): endpoint HTTPS que receberá o POST.
apiKey (opcional): se informado, a GYRA+ envia esse valor no header api-key de cada requisição, para o seu endpoint validar a origem.

Tipos de webhook

Cada disparo é um POST com o envelope { organizationId, webhookType, data }. O que muda entre os tipos é quando dispara e o conteúdo de data:

`type`	Quando dispara	O que vem em `data`
`REPORT_FINISHED`	Relatório totalmente processado (todas as integrações concluíram). É o evento mais usado.	`reportId`, `policyId`, `isFinalized`, `finalizedAt` e, se houve falha parcial, `errors.sections[]`.
`REPORT`	A cada seção concluída durante o processamento (granular, vários disparos por relatório).	Os dados da seção concluída em `content`.
`REPORT_STATUS`	Decisão manual (analista aprovou/rejeitou via `analyze`/`re-analyze`).	`reportId` e `analysis` com `status` (`REPORT_APPROVED`/`REPORT_REJECTED`), autor e data.
`REPORT_EXPORTED`	Exportação do relatório (PDF ou XLS) ficou pronta, ou falhou.	`reportId`, `exportUrl` (assinada) e `exportedAt`. Em falha, `exportUrl` vem `null` e há `error`.
`CREDIT_POLICY`	Política de crédito avaliada (resultado final do motor de regras).	`reportId`, `policyId`, `version`, `status`, `risk`, `score`, `date`.
`OPERATION`	Operação (fluxo multi-relatório com cadeia de políticas) concluiu com status final.	`operationId`, `operationResultId`, `document`, `status`.
`OPTIN`	Reservado para o fluxo de opt-in de onboarding.	Conforme o fluxo de onboarding contratado.

O que cada tipo retorna em `data`

{
  "organizationId": "6612a7f30000000000000001",
  "webhookType": "REPORT_FINISHED",
  "data": {
    "content": {
      "reportId": "6612a7f30000000000000001",
      "policyId": "6612a7f30000000000000010",
      "isFinalized": true,
      "finalizedAt": "2026-04-23T14:30:45Z",
      "errors": { "sections": ["PROCESSES"] }
    },
    "compress": false
  }
}

{
  "organizationId": "6612a7f30000000000000001",
  "webhookType": "CREDIT_POLICY",
  "data": {
    "content": {
      "reportId": "6612a7f30000000000000001",
      "policyId": "6612a7f30000000000000010",
      "version": 3,
      "status": "APPROVED",
      "risk": "LOW",
      "score": 720,
      "date": "2026-04-23T14:30:45Z"
    }
  }
}

{
  "organizationId": "6612a7f30000000000000001",
  "webhookType": "REPORT_STATUS",
  "data": {
    "reportId": "6612a7f30000000000000001",
    "analysis": {
      "userId": "user-id-ou-'Política de crédito'",
      "userName": "Nome do analista",
      "status": "REPORT_APPROVED",
      "date": "2026-04-23T14:35:00Z"
    }
  }
}

{
  "organizationId": "6612a7f30000000000000001",
  "webhookType": "REPORT_EXPORTED",
  "data": {
    "reportId": "6612a7f30000000000000001",
    "exportUrl": "https://...url-assinada...",
    "exportedAt": "2026-04-23T14:40:00Z"
  }
}

{
  "organizationId": "6612a7f30000000000000001",
  "webhookType": "OPERATION",
  "data": {
    "operationId": "6612a7f30000000000000100",
    "operationResultId": "6612a7f30000000000000101",
    "document": "43591367000130",
    "status": "APPROVED"
  }
}

{
  "organizationId": "6612a7f30000000000000001",
  "webhookType": "REPORT",
  "data": {
    "content": { "...dados da seção concluída..." },
    "compress": false
  }
}

Para a maioria das integrações, escute REPORT_FINISHED (resultado pronto) e/ou CREDIT_POLICY (decisão). Use REPORT apenas se precisar de atualizações seção a seção. Visão geral e boas práticas em Webhooks e tempo real.

curl --location 'https://gyra-core.gyramais.com.br/webhook' \
--header 'Authorization: Bearer {seu_token_jwt}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx"
}'

fetch("https://gyra-core.gyramais.com.br/webhook", {
  method: "POST",
  headers: {
    "Authorization": "Bearer {seu_token_jwt}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx"
})
})
  .then(res => res.json())
  .then(console.log)

import requests

url = "https://gyra-core.gyramais.com.br/webhook"
headers = {
  "Authorization": "Bearer {seu_token_jwt}"
}
payload = {
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

{
  "id": "69a20f96f5b9cb55d8e8a6a1",
  "organizationId": "65eb4989a4a87b9a94d1920f",
  "type": "REPORT_FINISHED",
  "url": "https://webhook-test.com/a0a7aadb8de3e",
  "apiKey": "xxx-xxx-xxx",
  "createdAt": "2026-02-27T21:41:42.013Z",
  "updatedAt": "2026-02-27T21:41:42.013Z"
}

{
  "code": 400,
  "message": "type must be one of the following values: REPORT, OPTIN, CREDIT_POLICY, REPORT_STATUS, REPORT_FINISHED, REPORT_EXPORTED, OPERATION,type should not be empty,url should not be empty,url must be a string"
}

{
  "code": 401,
  "message": "Token de acesso inválido."
}

Consultar políticas de decisão Consultar Webhook

Primeiros Passos

Conceitos Fundamentais

Guia do Toolbox

Fontes de Dados

Guias

Casos de Uso

MCP Server

Referência da API

Dicionário de Dados

Integrações

Referência

Quando usar

Autenticação

Corpo da requisição

Tipos de webhook

O que cada tipo retorna em `data`

​Quando usar

​Autenticação

​Corpo da requisição

​Tipos de webhook

​O que cada tipo retorna em data

Quando usar

Autenticação

Corpo da requisição

Tipos de webhook

O que cada tipo retorna em `data`