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

# Transaction

### **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 [Trust Platform](https://trust.caf.io/) and enter the desired template and edit the **Webhook** field.

> * _Each Query Template created in the CAF_ [_Trust Platform_](https://trust.caf.io/profile-templates/profile-models) _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_ <mark style="color:green;">/</mark><mark style="color:green;">`transaction`</mark> _service endpoint point may receive as an optional parameter_ <mark style="color:green;">`_callbackUrl`</mark> _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_ [_Create a transaction page_](https://github.com/combateafraude/public-docs/blob/docs-api/core-api/webhooks/available-resources/transaction.md#transactions)_._

{% hint style="info" %}
[_<mark style="color:blue;">**Webhook Tester**</mark>_](https://webhook.site/) _<mark style="color:blue;">\*\*\*\*</mark> and_ [_**Request Bin**_](https://requestbin.com/) _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._
{% endhint %}

### **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.

{% hint style="warning" %}
The status of a transaction is defined based on the validations configured in the query template.
{% endhint %}

### Webhook response parameters

| Name                                     | Type   | Description                                                                                                                  |
| ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| type<mark style="color:red;">\*</mark>   | String | Type of the event (process\_started, status\_updated or documentscopy\_requested)                                            |
| report<mark style="color:red;">\*</mark> | String | Report identifier (legacy flow support). If the transaction has no report, the value will return as 000000000000000000000000 |
| uuid<mark style="color:red;">\*</mark>   | String | Transaction identifier                                                                                                       |
| status<mark style="color:red;">\*</mark> | String | Status of the transaction                                                                                                    |
| date<mark style="color:red;">\*</mark>   | 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:

```json
{
  "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.
