> 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/connect/webhook/events.md).

# Events

This page describes the different events that can trigger webhook notifications in Connect API.

## Event structure

{% hint style="info" %}
Certta webhooks follow the [CloudEvents](https://cloudevents.io/) specification for the `JSON` event structure, a CNCF standard for describing event data in a common way. This standardized format makes it easier to integrate with your systems and ensures consistency across different event sources. Note that while the body follows the CloudEvents format, the CloudEvents `HTTP` headers are not included in the request.
{% endhint %}

Each webhook event follows this CloudEvents-compliant structure:

```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"
  }
}
```

| Field             | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `id`              | Unique identifier for the event                           |
| `source`          | URI indicating where the event originated                 |
| `specversion`     | CloudEvents specification version (currently 1.0)         |
| `type`            | Type of the event (see Event Types below)                 |
| `time`            | Timestamp when the event occurred (ISO 8601 format)       |
| `datacontenttype` | Media type of the data value (typically application/json) |
| `data`            | Object containing event-specific data                     |

## Event types

Connect currently supports the following event types:

### Communication

| Event Type                            | Description                                         |
| ------------------------------------- | --------------------------------------------------- |
| `COMMUNICATIONCREATEDEVENT`           | A new communication has been created                |
| `COMMUNICATIONDELIVEREDEVENT`         | A communication has been delivered to the recipient |
| `COMMUNICATIONREJECTEDEVENT`          | A communication was rejected                        |
| `COMMUNICATIONNOTDELIVEREDEVENT`      | A communication was not delivered to the recipient  |
| `COMMUNICATIONSENTTODESTINATIONEVENT` | A communication was sent to its destination         |

### Transaction

| Event Type                               | Description                                                                                             |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `TRANSACTIONPROCESSSTARTEDEVENT`         | A transaction created by Web Onboarding started processing after the user completed the onboarding flow |
| `TRANSACTIONSTATUSUPDATEDEVENT`          | A transaction's status has been updated                                                                 |
| `TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT` | A request for documents copy in a transaction was made                                                  |

{% hint style="warning" %}
`TRANSACTIONPROCESSSTARTEDEVENT` is specific to transactions initiated after a user completes a Web Onboarding flow. It is not a generic transaction-created event and is not emitted when a transaction is created directly through the Transactions API.
{% endhint %}

### SmartAuth

| Event Type                | Description                                |
| ------------------------- | ------------------------------------------ |
| `FACEAUTHENTICATIONEVENT` | A face authentication attempt has occurred |
| `PROFILEUPDATEDEVENT`     | A profile's status has been updated        |

## Event handling guidelines

{% hint style="info" %}

### Best practices for event consumers

1. **Event Type Validation**: Always validate the event type before processing.
2. **Error Handling**: Implement robust error handling for malformed events.
3. **Idempotent Processing**: Process events idempotently using the event `id` to avoid duplicate processing.
4. **Field Presence Checks**: Don't assume all fields will always be present in the event payload.
5. **Event Order**: Don't rely on events arriving in chronological order.
   {% endhint %}

## Future event types

Certta is continuously expanding its event offerings. Check the documentation regularly for updates on newly supported event types. If you need events for specific state changes not currently available, contact Certta support.

{% hint style="warning" %}
Certta may add new fields to existing event types without considering it a breaking change. Your event processing should be designed to handle additional fields gracefully.
{% endhint %}

## Event examples

### Communication event examples

#### 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": "Invalid phone number format"
  }
}
```

#### 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": "Recipient's phone is unreachable"
  }
}
```

{% hint style="info" %}

### Common data fields in communication events

All communication events include these common fields in the `data` object:

Some events may include additional fields:
{% endhint %}

| Field    | Description                                                       |
| -------- | ----------------------------------------------------------------- |
| `reason` | Reason for rejection or failure (in REJECTED/NOTDELIVERED events) |

| Field            | Description                                                |
| ---------------- | ---------------------------------------------------------- |
| `tenantId`       | Identifier of the tenant associated with the communication |
| `channel`        | Communication channel (e.g., "sms", "email", "whatsapp")   |
| `externalId`     | External identifier for the communication                  |
| `notificationId` | Unique identifier for the notification                     |
| `system`         | System that originated the communication                   |
| `occurredOn`     | Timestamp when the event occurred                          |

### Handling communication events

When processing communication events, consider the following best practices:

{% hint style="success" %}
**Communication Event Lifecycle**

Communications typically follow this event sequence:

1. `COMMUNICATIONCREATEDEVENT` - Initial creation
2. `COMMUNICATIONSENTTODESTINATIONEVENT` - Sent to delivery provider
3. One of:
   * `COMMUNICATIONDELIVEREDEVENT` - Successfully delivered
   * `COMMUNICATIONNOTDELIVEREDEVENT` - Delivery failed
   * `COMMUNICATIONREJECTEDEVENT` - Rejected before sending

Your application should be prepared to handle these events in any order, as delivery status updates may not always arrive in sequence.
{% endhint %}

{% hint style="warning" %}
**Event Handling Recommendations**

* Always check the event `type` before processing to ensure correct handling logic
* Store communication statuses using both the `notificationId` and `externalId` for correlation
* Implement idempotent event handling to avoid issues if you receive duplicate events
* Pay special attention to `COMMUNICATIONREJECTEDEVENT` and `COMMUNICATIONNOTDELIVEREDEVENT` as these may require follow-up actions in your system
  {% endhint %}

## Transaction events

Transaction events provide real-time updates about the status and lifecycle of transactions in your system.

### Transaction event examples

#### 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"
  }
}
```

{% hint style="info" %}

### Common data fields in transaction events

Transaction events use the following fields in the `data` object. Fields described as optional are omitted when they do not apply:
{% endhint %}

| Field          | Description                                                                                                                        |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `tenantId`     | Identifier of the tenant associated with the transaction                                                                           |
| `report`       | Report identifier for legacy-flow compatibility. When no report is available, the value is `000000000000000000000000`              |
| `id`           | Unique identifier for the transaction                                                                                              |
| `status`       | Current business status of the transaction. See Transaction status values below                                                    |
| `date`         | Timestamp when the event occurred                                                                                                  |
| `onboardingId` | Identifier of the onboarding process that generated the transaction. Only present for transactions originating from Web Onboarding |
| `templateId`   | Identifier of the query template used for this transaction, when available                                                         |
| `customStatus` | Optional merchant-defined custom status configured in Trust. Omitted when no custom status applies                                 |

### Transaction status values

The `status` field represents the transaction's business result or processing state. It does not represent the webhook event lifecycle.

| Value         | Description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| `PROCESSING`  | The transaction is still being processed and its data may change                          |
| `APPROVED`    | The transaction passed the configured validation rules                                    |
| `REPROVED`    | The transaction contains an irregularity or evidence of fraud                             |
| `PENDING`     | The transaction requires a decision or manual action in Trust                             |
| `PENDING_OCR` | The document or its data could not be identified automatically and requires manual action |

{% hint style="info" %}
The event `type` describes what happened, while `data.status` describes the transaction's current business status. For example, a `TRANSACTIONPROCESSSTARTEDEVENT` or `TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT` may carry `status: "PROCESSING"`.
{% endhint %}

### Custom status values

`customStatus` is optional and does not have a global list of values. Its possible values are defined by each merchant's workflow configuration in Trust. Integrations must therefore treat it as a tenant-specific string and must not assume that values used by one tenant are available to another tenant.

When no merchant-defined status applies, `customStatus` is omitted from the event. Use `status` for the standard Connect transaction state and `customStatus` only for tenant-specific mapping.

Detailed validation reasons are not included in transaction event payloads. Use `GET /transactions/{transactionId}` with `data.id` to retrieve the complete transaction details.

### Handling transaction events

When processing transaction events, consider the following best practices:

{% hint style="success" %}
**Transaction Event Lifecycle**

Transactions originating from Web Onboarding typically follow this sequence:

1. `POST /onboardings` returns an onboarding link. No transaction exists and no transaction event is emitted at this point.
2. `TRANSACTIONPROCESSSTARTEDEVENT` - The user completed the onboarding flow and the resulting transaction started processing.
3. `TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT` - Documents are requested for processing (if applicable).
4. `TRANSACTIONSTATUSUPDATEDEVENT` - Status changes as processing progresses.
   * May be emitted multiple times as the transaction moves through various stages

Transactions created directly through the Transactions API do not emit `TRANSACTIONPROCESSSTARTEDEVENT`. Your application should use the transaction identifier returned by the creation request and track subsequent `TRANSACTIONSTATUSUPDATEDEVENT` events.

For either flow, the relevant transaction events must be enabled in the webhook's event selection in Trust.

The CloudEvents top-level `id` identifies the webhook event. The `data.id` field identifies the transaction and should be used to correlate transaction events.
{% endhint %}

## SmartAuth events

SmartAuth events provide information about authentication attempts and profile updates.

### SmartAuth event examples

#### 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" %}

### Data fields in SmartAuth events

**FACEAUTHENTICATIONEVENT fields:**

**PROFILEUPDATEDEVENT fields:**
{% endhint %}

| Field       | Description                                                         |
| ----------- | ------------------------------------------------------------------- |
| `tenantId`  | Identifier of the tenant associated with the profile                |
| `profileId` | Unique identifier for the profile                                   |
| `type`      | Type of profile (PF for individual, PJ for company)                 |
| `status`    | Current status of the profile                                       |
| `updatedAt` | Timestamp when the profile was updated                              |
| `cpf`       | Brazilian individual taxpayer registry identifier (when applicable) |
| `cnpj`      | Brazilian company registry identifier (when applicable)             |

| Field          | Description                                                       |
| -------------- | ----------------------------------------------------------------- |
| `tenantId`     | Identifier of the tenant associated with the authentication       |
| `onboardingId` | Identifier of the associated onboarding process                   |
| `personId`     | Identifier of the person being authenticated                      |
| `attemptId`    | Unique identifier for this authentication attempt                 |
| `isMatch`      | Boolean indicating whether the face authentication was successful |
| `date`         | Timestamp when the authentication occurred                        |

### Handling SmartAuth events

When processing SmartAuth events, consider the following best practices:

{% hint style="success" %}
**SmartAuth Event Handling**

For `FACEAUTHENTICATIONEVENT`:

* Check the `isMatch` field to determine authentication success
* Use the `personId` to correlate with your user records
* Consider implementing additional security measures for failed authentication attempts

For `PROFILEUPDATEDEVENT`:

* Update your local user records with the latest profile status
* Take appropriate actions based on status changes (e.g., enabling/disabling features)
* Store both `profileId` and document identifiers (`cpf`/`cnpj`) for correlation
  {% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.caf.io/caf-api/connect/webhook/events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.