Handling Transaction Errors

Transaction Error Webhook #

Cyclr’s Transaction Error Webhook feature enables you to be notified when Step Errors (and optionally Step Warnings) occur in your integrations, as a way of alerting you or your support staff.

Notifications are sent as HTTP POST requests to a URL you specify. They include JSON content in the request body that provides details of the error – or warning – encountered.

They can be turned on from within your Cyclr Console under Settings > General Settings, then by selecting the Enable Transaction Error Webhook option, providing a URL for Cyclr to notify, and selecting the Save button at the bottom of the page:

You can also choose to be notified when Step Warnings occur by using the additional Transaction Error Webhook Include Warnings option.

Account-level Override #

If you wish, you can choose to handle errors in particular Cyclr Accounts differently by using the Account-level override.

In your Cyclr Console, go to Accounts > Account Management, click Settings for the Account you wish to set this for and use the Transaction Error Webhook options found there. They work in exactly the same way as the Console-level options.

Transaction Error Webhook URL #

The URL you set for the Transaction Error Webhook could be for a third party system or a system of your own; any URL that will accept a POST request containing the JSON data Cyclr includes.

You’re also able to send these notifications to a Webhook Step in a Template or Cycle within Cyclr itself, allowing you to process the data using Decision Steps and other tools, just as you would any other data in Cyclr. This enables you to install Connectors such as Slack or SendGrid as a way to alert you, or database Connectors to log the details for future reference.

If you choose to handle these notifications within Cyclr, you should install the Error Webhook Connector which knows the structure of the request data Cyclr sends so is simpler to setup than perhaps using a standard Generic Webhook Connector’s Webhook Method.

Note: Using Cyclr’s Error Webhook Connector does not count towards your Connector Allowance, though Tasks used by Steps using its “Webhook” Method do count towards your Task Allowance, where present.

Handling Errors within Cyclr #

1. It is recommended to create a separate Folder perhaps called “Monitoring” to put your Template or Cycle into. It’s up to you whether you do this in your Cyclr Console as a Template or create a new Account dedicated to these types of processes.
2. Install the Error Webhook Connector – it has a Webhook Method which knows the structure of Cyclr’s Transaction Error Webhook requests.
3. Add that Connector’s Webhook Step to your integration.
4. In the Webhook’s Step Setup, select and copy the Webhook URL value.
5. Go to your Cyclr Console, and select Settings > General Settings.
6. Tick the box for Enable Transaction Error Webhook
7. Paste in the URL you copied from the Webhook Step.
8. Select the Save button to store those settings.

Now you can go back to the Cycle where you added the Webhook Step, and add any Decision Steps, etc to filter how errors will be handled.

In the example below, any errors relating to “Account 12345” will trigger a message in Slack.

Example Transaction Error Webhook Payload #

This example shows an error from Salesforce’s API when calling the “Get Account” Connector Method:

{
    "Timestamp": "2025-04-11T07:37:47.455544Z",
    "AccountId": "0bd9f087-8db9-46e9-8640-e8eb8a6fd635",
    "AccountExternalId": "0bd9f087-8db9-46e9-8640-e8eb8a6fd635",
    "AccountName": "Templates",
    "CycleId": "a2115f94-4ee6-4c4b-a03c-f89ce5ec41ed",
    "CycleName": "SF Updated Opps to Google",
    "StepId": "5c881e9f-5a38-4544-9b36-562baf4a2e71",
    "StepName": "Get Account",
    "StepType": 1,
    "TransactionId": "284bc7b4-4321-4c97-aa2f-370f9627d244",
    "Message": "Failed to call the method",
    "Detail": "404 Not Found\r\n[{\"errorCode\":\"NOT_FOUND\",\"message\":\"Provided external ID field does not exist or is not accessible: AAA\"}]\r\n\r\n\r\nHTTP Request:\r\nGET https://xxxxxxxxxxxxxxxxx-dev-ed.my.salesforce.com/services/data/v43.0/sobjects/Account/AAA?fields=Name HTTP/1.1\r\nAccept: application/json\r\nAuthorization: REDACTED\r\nUser-Agent: Cyclr, (https://cyclr.com)",
    "DetailTruncated": false,
    "IncidentLevel": "Error"
}

The information in the Detail property contains the original response Cyclr received from Salesforce.

As a result, it will change depending on the API being called and how that API formats its error responses.

If there are specific errors you wish to handle, you may need to force them to occur so that you can view their responses to see what information they contain.

Payload Properties #

Property	Description
Timestamp	String An ISO 8601 date/time string, indicating when the error occurred.
AccountId	String The Cyclr ID of the Account where the error occured.
AccountExternalId	String The API ID of the Account where the error occurred
AccountName	String The Name of the Account where the error occurred.
CycleId	String The ID of the related Cycle.
CycleName	String The Name of the related Cycle.
StepId	String The ID of the Step in the Cycle.
StepName	String The Name of the Step in the Cycle.
StepType	Integer Indicates the type of the Step where the error occured. Values are: 0 – None 1 – Action 2 – Webhook 3 – Decision 4 – Delay 5 – WaitUntil 6 – WaitAll 7 – WebhookResponse 8 – Annotation 9 – Switch 10 – McpRequest 11 – McpResponse
TransactionId	String The ID of the Transaction the error occurred within.
Message	String A short description of the error. Possible values: *Trigger Skipped *Transaction Stopped *Out of retries *Failed to authenticate the connector *Required source is empty *Webhook failed *Failed to build the request *Response data not in expected format *Failed to call the method *Response data fields missing *Step data cannot be split *Failed to split transaction step data *Failed to save the webhook response *Failed to return the webhook response *Failed to build the webhook response *Failed to find the webhook source key *Failed to get webhook trigger step data *Failed to find webhook trigger step *Wait Until Failed To Run *Wait Until is over retention period *Field is not a valid DateTime *WaitUntil step is missing wait criteria
Detail	String The original error received from the external system. If this is longer than 5,000 characters, it will be truncated and the separate DetailTruncated property will be set to true.
DetailTruncated	Boolean If the original response from the external system was longer than 5,000 characters, Detail will contain a truncated version ending in ... and DetailTruncated will be true, else false. The original response can be retrieved through the Cyclr API by retrieving details of the Transaction.
IncidentLevel	String Indicates how Cyclr recorded the error: * Error – recorded as a Step Error. * Warning – recorded as a Step Warning. Step Warnings will only be sent by Cyclr if the additional Transaction Error Webhook Include Warnings option has been enabled.