Webhooks

Setting up the webhook

There are two ways to configure a webhook: by linking it to a workflow or entering it directly in the request when creating a transaction. Configuring workflow webhook can be done via the Trust platform by going to workflow builder and selected the desired workflow. Once there, navigate to settings menu and edit the webhook field.

For setting up the webhook endpoint when creating a transaction, it is necessary to send the property webhookUrl inside metadata on the request body.

{
  "metadata": {
    "webhookUrl": "https://example.com"
  }
}

It is relevant to notice that we will ignore the webhook configured on workflow if there is one on the transaction's metadata.

Webhook URL must be able to receive an HTTP POST request from CAF services.

Webhook notifications

By default, CAF will return notifications of transaction updates via webhooks to the end client URL that has already been set up in the configuration. You will receive a notification via webhook whenever a transaction starts, finishes, or is set to pending status.

Besides that, in the future, CAF can add new webhooks about the transaction flow and/or new fields, so your application must be ready to receive them. A good practice is checking the webhook type before taking any action on your side, and you must follow the Tolerant Reader pattern.

Webhook response parameters

NameTypeDescription

id

string

Event unique identifier.

time

string

Timestamp of when the occurrence happened.

type

string

This attribute contains a value describing the type of event related to the originating occurrence (TransactionCreated, TransactionFinished or TransactionPending).

source

string

Identifies the context in which an event happened.

specVersion

string

The version of the CloudEvents specification which the event uses.

data

object

The event payload.

data.transactionId

string

Transaction unique identifier.

data.workflowId

string

Workflow unique identifier.

data.status

string

Transaction status.

data.date

string

Timestamp of when the webhook is sent.

data.metadata

object

Transaction metadata, where you might have other attributes like the onboarding unique identifier related to the transaction, in case it exists.

Example webhook post:

{
    "id": "08934216-a945-43b1-a3f3-bd39869fd9fc",
    "time": "2023-08-01T13:10:25.791Z",
    "type": "TransactionFinished",
    "source": "https://api.public.caf.io/v1/orchestrations",
    "specversion": "1.0",
    "data": {
        "transactionId": "6021a21b3811c35ecb8dea20",
        "workflowId": "7011a21b3811c35ecb8dea21",
        "status": "APPROVED",
        "date": "2023-08-01T13:10:25.791Z",
        "metadata": {
          "onboardingId": "6021a21b3811c35ecb8dea22"
        }
    }
}

Error handling

If we cannot communicate with your webhook, we will make up to 5 attempts in a maximum of 26 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.

Last updated

Logo

2023 © Caf. - All rights reserved