> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/caf-api-pt-br/conectar/webhook/events.md).

# Eventos

Esta página descreve os diferentes eventos que podem disparar notificações de webhook na API Connect.

## Estrutura do evento

{% hint style="info" %}
Os webhooks da Certta seguem a [CloudEvents](https://cloudevents.io/) especificação para a `JSON` estrutura do evento, um padrão da CNCF para descrever dados de eventos de forma comum. Esse formato padronizado facilita a integração com seus sistemas e garante consistência entre diferentes fontes de eventos. Observe que, embora o corpo siga o formato CloudEvents, os `HTTP` headers do CloudEvents não estão incluídos na solicitação.
{% endhint %}

Cada evento de webhook segue esta estrutura compatível com CloudEvents:

```json
{
  "specversion": "1.0",
  "type": "COMMUNICATIONCREATEDEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQB",
  "time": "2025-07-08T18:01:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:00:46.797Z"
  }
}
```

| Campo             | Descrição                                                       |
| ----------------- | --------------------------------------------------------------- |
| `id`              | Identificador exclusivo do evento                               |
| `source`          | URI indicando onde o evento se originou                         |
| `specversion`     | Versão da especificação CloudEvents (atualmente 1.0)            |
| `type`            | Tipo do evento (veja Tipos de Evento abaixo)                    |
| `time`            | Carimbo de data/hora em que o evento ocorreu (formato ISO 8601) |
| `datacontenttype` | Tipo de mídia do valor dos dados (normalmente application/json) |
| `data`            | Objeto contendo dados específicos do evento                     |

## Tipos de evento

Atualmente, o Connect oferece suporte aos seguintes tipos de evento:

### Comunicação

| Tipo de Evento                        | Descrição                                        |
| ------------------------------------- | ------------------------------------------------ |
| `COMMUNICATIONCREATEDEVENT`           | Uma nova comunicação foi criada                  |
| `COMMUNICATIONDELIVEREDEVENT`         | Uma comunicação foi entregue ao destinatário     |
| `COMMUNICATIONREJECTEDEVENT`          | Uma comunicação foi rejeitada                    |
| `COMMUNICATIONNOTDELIVEREDEVENT`      | Uma comunicação não foi entregue ao destinatário |
| `COMMUNICATIONSENTTODESTINATIONEVENT` | Uma comunicação foi enviada para o destino       |

### Transação

| Tipo de Evento                           | Descrição                                                                                                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRANSACTIONPROCESSSTARTEDEVENT`         | Uma transação criada pelo Web Onboarding começou a ser processada após o usuário concluir o fluxo de onboarding                                                             |
| `TRANSACTIONSTATUSUPDATEDEVENT`          | O status de uma transação foi atualizado                                                                                                                                    |
| `TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT` | Uma solicitação de cópia de documentos em uma transação foi feita                                                                                                           |
| `TRANSACTIONVERIFAIDOCSERROREVENT`       | A análise VerifAI Docs de uma transação falhou e os arquivos enviados não foram retidos. Emitido apenas para contas com a retenção zero em erros do VerifAI Docs habilitada |

{% hint style="warning" %}
`TRANSACTIONPROCESSSTARTEDEVENT` é específico para transações iniciadas após um usuário concluir um fluxo de Web Onboarding. Não é um evento genérico de criação de transação e não é emitido quando uma transação é criada diretamente pela API de Transações.
{% endhint %}

### SmartAuth

| Tipo de Evento            | Descrição                                    |
| ------------------------- | -------------------------------------------- |
| `FACEAUTHENTICATIONEVENT` | Uma tentativa de autenticação facial ocorreu |
| `PROFILEUPDATEDEVENT`     | O status de um perfil foi atualizado         |

## Diretrizes de tratamento de eventos

{% hint style="info" %}

### Melhores práticas para consumidores de eventos

1. **Validação do Tipo de Evento**: Sempre valide o tipo do evento antes de processá-lo.
2. **Tratamento de Erros**: Implemente um tratamento robusto de erros para eventos malformados.
3. **Processamento Idempotente**: Processe eventos de forma idempotente usando o evento `id` para evitar processamento duplicado.
4. **Verificações de Presença de Campos**: Não assuma que todos os campos estarão sempre presentes no payload do evento.
5. **Ordem dos Eventos**: Não dependa de os eventos chegarem em ordem cronológica.
   {% endhint %}

## Tipos de evento futuros

A Certta está expandindo continuamente suas ofertas de eventos. Consulte a documentação regularmente para atualizações sobre novos tipos de evento com suporte. Se você precisar de eventos para mudanças de estado específicas que ainda não estejam disponíveis, entre em contato com o suporte da Certta.

{% hint style="warning" %}
A Certta pode adicionar novos campos aos tipos de evento existentes sem considerar isso uma alteração que quebre compatibilidade. Seu processamento de eventos deve ser projetado para lidar com campos adicionais de forma adequada.
{% endhint %}

## Exemplos de eventos

### Exemplos de eventos de comunicação

#### COMMUNICATIONCREATEDEVENT

```json
{
  "specversion": "1.0",
  "type": "COMMUNICATIONCREATEDEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQB",
  "time": "2025-07-08T18:01:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:00:46.797Z"
  }
}
```

#### COMMUNICATIONREJECTEDEVENT

```json
{
  "specversion": "1.0",
  "type": "COMMUNICATIONREJECTEDEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQC",
  "time": "2025-07-08T18:02:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:02:46.797Z",
    "reason": "Formato de número de telefone inválido"
  }
}
```

#### COMMUNICATIONSENTTODESTINATIONEVENT

```json
{
  "specversion": "1.0",
  "type": "COMMUNICATIONSENTTODESTINATIONEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQD",
  "time": "2025-07-08T18:03:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:03:46.797Z"
  }
}
```

#### COMMUNICATIONDELIVEREDEVENT

```json
{
  "specversion": "1.0",
  "type": "COMMUNICATIONDELIVEREDEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQE",
  "time": "2025-07-08T18:04:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:04:46.797Z"
  }
}
```

#### COMMUNICATIONNOTDELIVEREDEVENT

```json
{
  "specversion": "1.0",
  "type": "COMMUNICATIONNOTDELIVEREDEVENT",
  "source": "COMMUNICATION",
  "id": "01JZNK5ZQBNF623MB5KE64GNQF",
  "time": "2025-07-08T18:05:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "channel": "sms",
    "externalId": "external-id",
    "notificationId": "01JZNK51YCZXT55TKF8M366QHJ",
    "system": "onboarding",
    "occurredOn": "2025-07-08T18:05:46.797Z",
    "reason": "O telefone do destinatário está inacessível"
  }
}
```

{% hint style="info" %}

### Campos de dados comuns em eventos de comunicação

Todos os eventos de comunicação incluem estes campos comuns no `data` objeto:

| Campo            | Descrição                                                      |
| ---------------- | -------------------------------------------------------------- |
| `tenantId`       | Identificador do tenant associado à comunicação                |
| `channel`        | Canal de comunicação (por exemplo, "sms", "email", "whatsapp") |
| `externalId`     | Identificador externo da comunicação                           |
| `notificationId` | Identificador exclusivo da notificação                         |
| `system`         | Sistema que originou a comunicação                             |
| `occurredOn`     | Carimbo de data/hora em que o evento ocorreu                   |

Alguns eventos podem incluir campos adicionais:

| Campo         | Descrição                                                      |
| ------------- | -------------------------------------------------------------- |
| `reason`      | Motivo da rejeição ou falha (em eventos REJECTED/NOTDELIVERED) |
| {% endhint %} |                                                                |

### Tratamento de eventos de comunicação

Ao processar eventos de comunicação, considere as seguintes melhores práticas:

{% hint style="success" %}
**Ciclo de vida do evento de comunicação**

As comunicações normalmente seguem esta sequência de eventos:

1. `COMMUNICATIONCREATEDEVENT` - Criação inicial
2. `COMMUNICATIONSENTTODESTINATIONEVENT` - Enviado ao provedor de entrega
3. Um dos seguintes:
   * `COMMUNICATIONDELIVEREDEVENT` - Entregue com sucesso
   * `COMMUNICATIONNOTDELIVEREDEVENT` - Falha na entrega
   * `COMMUNICATIONREJECTEDEVENT` - Rejeitado antes do envio

Seu aplicativo deve estar preparado para lidar com esses eventos em qualquer ordem, já que as atualizações de status de entrega nem sempre chegam em sequência.
{% endhint %}

{% hint style="warning" %}
**Recomendações para tratamento de eventos**

* Sempre verifique o evento `type` antes de processar para garantir a lógica correta de tratamento
* Armazene os status de comunicação usando tanto o `notificationId` e `externalId` para correlação
* Implemente o tratamento idempotente de eventos para evitar problemas caso você receba eventos duplicados
* Preste atenção especial a `COMMUNICATIONREJECTEDEVENT` e `COMMUNICATIONNOTDELIVEREDEVENT` pois isso pode exigir ações de acompanhamento no seu sistema
  {% endhint %}

## Eventos de transação

Os eventos de transação fornecem atualizações em tempo real sobre o status e o ciclo de vida das transações no seu sistema.

### Exemplos de eventos de transação

#### TRANSACTIONPROCESSSTARTEDEVENT

```json
{
  "specversion": "1.0",
  "type": "TRANSACTIONPROCESSSTARTEDEVENT",
  "source": "TRANSACTION",
  "id": "01JZNL6XQBNF623MB5KE64GNQB",
  "time": "2025-07-08T19:01:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "report": "000000000000000000000000",
    "id": "01JZNL6XQBNF623MB5KE64GNQB",
    "status": "PROCESSING",
    "date": "2025-07-08T19:01:19.622Z",
    "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC",
    "templateId": "document-ocr-basic"
  }
}
```

#### TRANSACTIONSTATUSUPDATEDEVENT

```json
{
  "specversion": "1.0",
  "type": "TRANSACTIONSTATUSUPDATEDEVENT",
  "source": "TRANSACTION",
  "id": "01JZNL6XQBNF623MB5KE64GNQD",
  "time": "2025-07-08T19:05:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "report": "000000000000000000000000",
    "id": "01JZNL6XQBNF623MB5KE64GNQB",
    "status": "APPROVED",
    "date": "2025-07-08T19:05:19.622Z",
    "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC",
    "templateId": "document-ocr-basic",
    "customStatus": "LOW_RISK_APPROVED"
  }
}
```

#### TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT

```json
{
  "specversion": "1.0",
  "type": "TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT",
  "source": "TRANSACTION",
  "id": "01JZNL6XQBNF623MB5KE64GNQE",
  "time": "2025-07-08T19:03:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "report": "000000000000000000000000",
    "id": "01JZNL6XQBNF623MB5KE64GNQB",
    "status": "PROCESSING",
    "date": "2025-07-08T19:03:19.622Z",
    "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC",
    "templateId": "document-ocr-basic"
  }
}
```

#### TRANSACTIONVERIFAIDOCSERROREVENT

```json
{
  "specversion": "1.0",
  "type": "TRANSACTIONVERIFAIDOCSERROREVENT",
  "source": "TRANSACTION",
  "id": "01JZNL6XQBNF623MB5KE64GNQF",
  "time": "2025-07-08T19:04:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "report": "000000000000000000000000",
    "id": "01JZNL6XQBNF623MB5KE64GNQB",
    "status": "PENDING",
    "date": "2025-07-08T19:04:19.622Z",
    "templateId": "document-ocr-basic"
  }
}
```

{% hint style="warning" %}
**Falha na análise do VerifAI Docs com retenção zero**

`TRANSACTIONVERIFAIDOCSERROREVENT` é emitido apenas para contas com o recurso de retenção zero em erros do VerifAI Docs habilitado. Quando a análise VerifAI Docs de uma transação falha, os arquivos enviados não são retidos e a análise não será reprocessada: crie uma nova transação se quiser uma nova análise.

* O evento é enviado **apenas uma vez por transação**.
* `data.status` contém o status da transação no momento do envio (`PENDING`, `REPROVED` ou outro valor, de acordo com as validações configuradas no modelo de consulta).
* O evento comunica a **decisão** não reter os arquivos, e não uma confirmação de que a exclusão já foi concluída.
  {% endhint %}

{% hint style="info" %}

### Campos de dados comuns em eventos de transação

Os eventos de transação usam os seguintes campos no `data` objeto. Os campos descritos como opcionais são omitidos quando não se aplicam:

| Campo          | Descrição                                                                                                                                        |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `tenantId`     | Identificador do tenant associado à transação                                                                                                    |
| `relatório`    | Identificador do relatório para compatibilidade com fluxos legados. Quando não houver relatório disponível, o valor é `000000000000000000000000` |
| `id`           | Identificador exclusivo da transação                                                                                                             |
| `status`       | Status comercial atual da transação. Veja os valores de status da transação abaixo                                                               |
| `data`         | Carimbo de data/hora em que o evento ocorreu                                                                                                     |
| `onboardingId` | Identificador do processo de onboarding que gerou a transação. Presente apenas para transações originadas do Web Onboarding                      |
| `templateId`   | Identificador do modelo de consulta usado para esta transação, quando disponível                                                                 |
| `customStatus` | Status personalizado opcional definido pelo comerciante e configurado no Trust. Omitido quando nenhum status personalizado se aplica             |
| {% endhint %}  |                                                                                                                                                  |

### Valores de status da transação

A `status` o campo representa o resultado de negócio ou o estado de processamento da transação. Ele não representa o ciclo de vida do evento de webhook.

| Valor         | Descrição                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------- |
| `PROCESSING`  | A transação ainda está sendo processada e seus dados podem mudar                             |
| `APPROVED`    | A transação passou pelas regras de validação configuradas                                    |
| `REPROVED`    | A transação contém uma irregularidade ou evidência de fraude                                 |
| `PENDING`     | A transação requer uma decisão ou ação manual no Trust                                       |
| `PENDING_OCR` | O documento ou seus dados não puderam ser identificados automaticamente e exigem ação manual |

{% hint style="info" %}
O evento `type` descreve o que aconteceu, enquanto `data.status` descreve o status comercial atual da transação. Por exemplo, uma `TRANSACTIONPROCESSSTARTEDEVENT` ou `TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT` pode conter `status: "PROCESSING"`.
{% endhint %}

### Valores de status personalizados

`customStatus` é opcional e não possui uma lista global de valores. Seus possíveis valores são definidos pela configuração de fluxo de trabalho de cada comerciante no Trust. As integrações devem, portanto, tratá-lo como uma string específica do tenant e não devem assumir que valores usados por um tenant estejam disponíveis para outro tenant.

Quando nenhum status definido pelo comerciante se aplicar, `customStatus` é omitido do evento. Use `status` para o estado padrão da transação no Connect e `customStatus` somente para mapeamento específico do tenant.

Motivos detalhados de validação não estão incluídos nos payloads dos eventos de transação. Use `GET /transactions/{transactionId}` com `data.id` para recuperar os detalhes completos da transação.

### Tratamento de eventos de transação

Ao processar eventos de transação, considere as seguintes melhores práticas:

{% hint style="success" %}
**Ciclo de vida do evento de transação**

Transações originadas do Web Onboarding normalmente seguem esta sequência:

1. `POST /onboardings` retorna um link de onboarding. Nenhuma transação existe e nenhum evento de transação é emitido neste momento.
2. `TRANSACTIONPROCESSSTARTEDEVENT` - O usuário concluiu o fluxo de onboarding e a transação resultante começou a ser processada.
3. `TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT` - Documentos são solicitados para processamento (se aplicável).
4. `TRANSACTIONSTATUSUPDATEDEVENT` - O status muda à medida que o processamento avança.
   * Pode ser emitido várias vezes à medida que a transação passa por várias etapas
5. `TRANSACTIONVERIFAIDOCSERROREVENT` - A análise VerifAI Docs falhou e os arquivos enviados não foram retidos (apenas para contas com a retenção zero em erros do VerifAI Docs habilitada).

Transações criadas diretamente pela API de Transações não emitem `TRANSACTIONPROCESSSTARTEDEVENT`. Seu aplicativo deve usar o identificador da transação retornado pela solicitação de criação e acompanhar os subsequentes `TRANSACTIONSTATUSUPDATEDEVENT` eventos.

Para qualquer um dos fluxos, os eventos de transação relevantes devem estar habilitados na seleção de eventos do webhook no Trust.

O nível superior do CloudEvents `id` identifica o evento de webhook. O `data.id` campo identifica a transação e deve ser usado para correlacionar eventos de transação.
{% endhint %}

## Eventos SmartAuth

Os eventos SmartAuth fornecem informações sobre tentativas de autenticação e atualizações de perfil.

### Exemplos de eventos SmartAuth

#### FACEAUTHENTICATIONEVENT

```json
{
  "specversion": "1.0",
  "type": "FACEAUTHENTICATIONEVENT",
  "source": "SMARTAUTH",
  "id": "01JZNL6XQBNF623MB5KE64GNQF",
  "time": "2025-07-08T19:10:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC",
    "personId": "01JZNL6XQBNF623MB5KE64GNQG",
    "attemptId": "01JZNL6XQBNF623MB5KE64GNQH",
    "isMatch": true,
    "date": "2025-07-08T19:10:19.622Z"
  }
}
```

#### PROFILEUPDATEDEVENT

```json
{
  "specversion": "1.0",
  "type": "PROFILEUPDATEDEVENT",
  "source": "SMARTAUTH",
  "id": "01JZNL6XQBNF623MB5KE64GNQI",
  "time": "2025-07-08T19:15:19.622Z",
  "datacontenttype": "application/json",
  "data": {
    "tenantId": "016e8f79-2399-4d35-90f9-c6f91b73189d",
    "profileId": "01JZNL6XQBNF623MB5KE64GNQJ",
    "type": "PF",
    "status": "APPROVED",
    "updatedAt": "2025-07-08T19:15:19.622Z",
    "cpf": "12345678901",
    "cnpj": null
  }
}
```

{% hint style="info" %}

### Campos de dados em eventos SmartAuth

**Campos do FACEAUTHENTICATIONEVENT:**

| Campo          | Descrição                                                    |
| -------------- | ------------------------------------------------------------ |
| `tenantId`     | Identificador do tenant associado à autenticação             |
| `onboardingId` | Identificador do processo de onboarding associado            |
| `personId`     | Identificador da pessoa sendo autenticada                    |
| `attemptId`    | Identificador exclusivo desta tentativa de autenticação      |
| `isMatch`      | Booleano indicando se a autenticação facial foi bem-sucedida |
| `data`         | Carimbo de data/hora em que a autenticação ocorreu           |

**Campos do PROFILEUPDATEDEVENT:**

| Campo         | Descrição                                               |
| ------------- | ------------------------------------------------------- |
| `tenantId`    | Identificador do tenant associado ao perfil             |
| `profileId`   | Identificador exclusivo do perfil                       |
| `type`        | Tipo de perfil (PF para pessoa física, PJ para empresa) |
| `status`      | Status atual do perfil                                  |
| `updatedAt`   | Carimbo de data/hora em que o perfil foi atualizado     |
| `cpf`         | Identificador do CPF (quando aplicável)                 |
| `cnpj`        | Identificador do CNPJ (quando aplicável)                |
| {% endhint %} |                                                         |

### Tratamento de eventos SmartAuth

Ao processar eventos SmartAuth, considere as seguintes melhores práticas:

{% hint style="success" %}
**Tratamento de eventos SmartAuth**

Para `FACEAUTHENTICATIONEVENT`:

* Verifique o `isMatch` campo para determinar o sucesso da autenticação
* Use o `personId` para correlacionar com seus registros de usuário
* Considere implementar medidas de segurança adicionais para tentativas de autenticação com falha

Para `PROFILEUPDATEDEVENT`:

* Atualize seus registros locais de usuário com o status de perfil mais recente
* Tome as ações apropriadas com base nas mudanças de status (por exemplo, habilitar/desabilitar recursos)
* Armazene tanto `profileId` quanto os identificadores de documento (`cpf`/`cnpj`) para correlação
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.caf.io/caf-api/caf-api-pt-br/conectar/webhook/events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
