Events

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

Event structure

Caf 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

Caf 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 process has started

TRANSACTIONSTATUSUPDATED

A transaction's status has been updated

TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT

A request for documents copy in a transaction was made

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

Caf.io 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 Caf.io support.

Caf.io 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

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

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

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

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

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

Common data fields in communication events

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

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

Some events may include additional fields:

Field
Description

reason

Reason for rejection or failure (in REJECTED/NOTDELIVERED events)

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

{
  "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": "STARTED",
    "date": "2025-07-08T19:01:19.622Z",
    "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC",
    "templateId": "document-ocr-basic",
    "customStatus": null
  }
}

TRANSACTIONSTATUSUPDATED

{
  "specversion": "1.0",
  "type": "TRANSACTIONSTATUSUPDATED",
  "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": "COMPLETED",
    "date": "2025-07-08T19:05:19.622Z",
    "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC",
    "templateId": "document-ocr-basic",
    "customStatus": "APPROVED"
  }
}

TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT

{
  "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": "IN_PROGRESS",
    "date": "2025-07-08T19:03:19.622Z",
    "onboardingId": "01JZNL6XQBNF623MB5KE64GNQC",
    "templateId": "document-ocr-basic",
    "customStatus": null
  }
}

Common data fields in transaction events

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

Field
Description

tenantId

Identifier of the tenant associated with the transaction

report

URL to access the detailed report for this transaction

id

Unique identifier for the transaction

status

Current status of the transaction (STARTED, IN_PROGRESS, COMPLETED, etc.)

date

Timestamp when the event occurred

onboardingId

Identifier of the associated onboarding process

templateId

Template identifier used for this transaction

customStatus

Optional custom status defined for the transaction workflow

Handling transaction events

When processing transaction events, consider the following best practices:

Transaction Event Lifecycle

Transactions typically follow this event sequence:

  1. TRANSACTIONPROCESSSTARTEDEVENT - Transaction process initiated

  2. TRANSACTIONDOCUMENTSCOPYREQUESTEDEVENT - Documents are requested for processing (if applicable)

  3. TRANSACTIONSTATUSUPDATED - Status changes as processing progresses

    • May be emitted multiple times as the transaction moves through various stages

Your application should track the transaction id to correlate these events.

SmartAuth events

SmartAuth events provide information about authentication attempts and profile updates.

SmartAuth event examples

FACEAUTHENTICATIONEVENT

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

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

Data fields in SmartAuth events

FACEAUTHENTICATIONEVENT fields:

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

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)

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