Comment on page

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 been already set up in the configuration. You will receive a notification via webhook whenever a transaction finishes or enter on pending status.
Webhook response parameters
Name
Type
Description
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 (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.
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"
    }
}
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.

Name	Type	Description
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 (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.

Last modified 3mo ago