Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Events

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

Event structure

Certta webhooks follow the CloudEvents 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.

Each webhook event follows this CloudEvents-compliant structure:

{
  "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

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.

SmartAuth

Event Type
Description

FACEAUTHENTICATIONEVENT

A face authentication attempt has occurred

PROFILEUPDATEDEVENT

A profile's status has been updated

Event handling guidelines

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.

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.

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.

Event examples

Communication event examples

COMMUNICATIONCREATEDEVENT

COMMUNICATIONREJECTEDEVENT

COMMUNICATIONSENTTODESTINATIONEVENT

COMMUNICATIONDELIVEREDEVENT

COMMUNICATIONNOTDELIVEREDEVENT

Common data fields in communication events

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

Some events may include additional fields:

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:

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.

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

Transaction events

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

Transaction event examples

TRANSACTIONPROCESSSTARTEDEVENT

TRANSACTIONSTATUSUPDATEDEVENT

TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT

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:

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

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".

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:

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.

SmartAuth events

SmartAuth events provide information about authentication attempts and profile updates.

SmartAuth event examples

FACEAUTHENTICATIONEVENT

PROFILEUPDATEDEVENT

Data fields in SmartAuth events

FACEAUTHENTICATIONEVENT fields:

PROFILEUPDATEDEVENT fields:

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:

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

Last updated