LogoLogo
Useful links
  • Home
  • Product guides
  • API
  • SDKs
  • Overview
  • CORE API
    • Authentication
    • Available resources
      • Transaction
      • Onboarding
      • Profile
      • Synchronous services
        • OCR Sync
        • Basic Data Sync (Individual)
    • Transaction details
      • Services
        • Document OCR
        • Documentscopy
        • Face Liveness
        • Facematch
        • Facial Biometrics
        • Private Faceset
        • Shared Faceset
        • Document Liveness
      • Background check
        • Data structure
        • KYC
          • Driver
          • Financial
          • Labor
          • Register data
          • Relationships
          • Risk
        • KYB
          • Financial
          • Labor
          • Register data
          • Risk
        • Vehicle
          • Register data
      • Validation rules
      • Manual reprovals
    • Webhooks
      • Transaction
      • Profile
      • Face authentication
  • MOBILE API
    • Authentication
    • Available resources
      • Face liveness (deprecated)
      • Face registration (deprecated)
      • Face authentication (deprecated)
    • Response signature
  • GLOBAL API
    • Authentication
    • Available resources
      • Services
        • Company search
        • Company record
        • Basic Data Sync (Individual)
        • Sanctions
      • Orchestrations
        • Transactions
          • Services
            • KYB
              • Credit Report
              • Business Identity
            • KYC
              • Adverse Media
              • PEPs
              • Sanctions
              • Warnings
              • Global identity verification
              • Global identity double verification
            • DOC ID
              • Global Document Verification
      • Onboardings
        • Links
    • Webhooks
  • SMART AUTH API
    • Authentication
    • Available resources
      • Authentications
      • Create identity
  • Joint resolution 6 API
    • Authentication
    • Available resources
      • Suspected fraud creation
      • Suspected fraud query
      • Suspected fraud update
      • Suspected fraud deletion
    • Using mTLS
    • Changelog
LogoLogo

2025 © Caf. - All rights reserved

On this page
  • Setting up the webhook
  • Webhook notifications
  • Webhook response parameters
  • Error handling
  1. CORE API
  2. Webhooks

Transaction

Transaction webhooks are used to communicate transaction status updates to the client-server.

Last updated 2 months ago

Setting up the webhook

There are two ways to set up a webhook: by linking it to a query template or entering it directly in the request when initiating a transaction. To configure the default webhook URL of a query template, navigate to the Query Templates menu on the CAF and enter the desired template and edit the Webhook field.

  • Each Query Template created in the CAF will need a call-back URL assigned for the webhooks. This URL can be different across active templates or the same.

  • The configured URL must be ready to expect a POST request following a CAF service execution.

  • The /transaction service endpoint point may receive as an optional parameter _callbackUrl with each transaction or onboarding request. The default URL configured in the associated query template will be ignored when using this parameter in any single request post. For more details regarding this override, go to the .

**** and are useful tools for receiving webhook calls. You can use them to generate a webhook URL and use that URL for any Postman requests that require you to specify a webhook URL, then use the sites to inspect the content of any webhooks they received.

Webhook notifications

You will receive a notification via webhook on the following events:

  • New transaction from web onboarding

Specifically, in web onboarding, a transaction is initiated when a user finishes the flow, and you will receive a notification of type process_started. It means that the documents have been captured and sent for review.

  • Sent to documentscopy

When the document has been sent to the documentscopy, you will receive a notification of the type documentscopy_requested. The status of the transaction remains PROCESSING until the documentscopy is complete.

  • Status change

When the transaction status changes, you will receive a status_updated notification.

The status of a transaction is defined based on the validations configured in the query template.

Webhook response parameters

Name
Type
Description

type*

String

Type of the event (process_started, status_updated or documentscopy_requested)

report*

String

Report identifier (legacy flow support). If the transaction has no report, the value will return as 000000000000000000000000

uuid*

String

Transaction identifier

status*

String

Status of the transaction

date*

String

Date when the webhook is sent as UTC format

onboardingId

String

If available, the identifier of the onboarding link used in the data capture.

templateId

String

Identifier of the transaction's query template, if it exists

statusReasons

Array

Reasons for the status

statusReasons[x].category

String

Reason category

statusReasons[x].code

String

Reason code

statusReasons[x].status

String

Reason status: ("VALID", "INVALID")

statusReasons[x].resultStatus

String

Result of the status: ("APPROVED", "REPROVED", "PENDING")

statusReasons[x].description

String

Reason description

Example webhook post:

{
  "report": "000000000000000000000000",
  "uuid": "xxxxxxxxxxxxxxxxxxxxxxxxx",
  "type": "status_updated",
  "status": "APPROVED",
  "date": "2023-08-16T16:27:32.801Z",
  "statusReasons": [
    {
      "category": "VALIDATION",
      "code": "over_18",
      "status": "VALID",
      "resultStatus": "APPROVED",
      "description": "Maior de idade (18 anos)."
    }
  ],
  "templateId": "xxxxxxxxxxxxxxxxxxxxxxxxx",
  "onboardingId": "yyyyyyyyyyyyyyyyyyyyyyyy",
}

Error handling

If we cannot communicate with your webhook, we will make up to 5 attempts in a maximum of 5 hours. During the time between requests, changes may occur in the transaction status. In case notifications are delivered out of chronological order, the status may not be mostly updated. Therefore, the recommendation is to consider the date attribute and always refer to the most recent transaction version.

Trust Platform
Trust Platform
Create a transaction page
Webhook Tester
Request Bin