Process webhooks in Creatio

Level: intermediate

note

This article covers the webhook processing relevant to Creatio 8.1.1 and later. Instructions for Creatio version 8.1.0 and earlier are listed in 8.0 documentation: Process webhooks in Creatio.

Use the Webhooks section (Fig. 1) of the Studio workplace to analyze incoming webhooks as well as view parsed results and errors in parsing.

Fig. 1 Webhooks section

Maintain webhooks

Creatio checks new webhooks every minute. If Creatio is not available for any reason at the time of receiving the webhook, Creatio service makes additional attempts to pass the webhook to Creatio 1 minute, 5 minutes, 60 minutes, 6 hours, 24 hours, 36 hours, 48 hours, 60 hours, and 72 hours later.

Creatio stores incoming webhooks in the Webhooks section. The section UI displays summary statistics of all incoming webhooks using the following dashboards:

• "Dynamics of received webhooks" chart. Visualizes dynamics of webhook processing by displaying summary statistics of all incoming webhooks without time limits.
• "Total," "Done" and "Failed" metrics. Displays the number of all incoming webhooks that have appropriate statuses. Click on the metrics to display detailed information webhooks that have the appropriate statuses.
• "Webhooks" list. Displays the list of all incoming webhooks.

You can filter webhooks on "Dynamics of received webhooks" chart and "Webhooks" dashboard list by status (Status drop-down list) and by date (Date range drop-down list).

Webhook status indicates the webhook lifecycle stage. View available webhook statuses in the table below.

Status	Status description
New	The newly incoming webhook.
Processing	The webhook is under processing.
Failed	The webhook parsing failed.
Done	The webhook was parsed successfully.

To display webhook details, double-click the webhook row in "Webhooks" dashboard list. This opens the webhook page (Fig. 2).

Fig. 2 Webhook details

Creatio deletes webhooks automatically after a specific period. The period values are as follows out of the box:

• 90 days for webhooks whose status is "New"
• 90 days for webhooks whose status is "Failed"
• 30 days for webhooks whose status is "Done"

You can specify the maximum period within which the webhook can remain in any status in the Webhook status lookup.

note

Deletion of a webhook does not delete the created record. Deletion of a webhook whose status is "Failed" deletes the connected log.

To delete the webhook manually, click → Delete in the webhook row.

Process webhooks

After Creatio retrieves a webhook, Creatio starts processing it.

Creatio platform uses the "Create object records based on incoming webhooks" business process that launches the "Create object records based on incoming webhook" business process out of the box.

Marketing Creatio product and Lead Generation composable app use the "Engagement tools App: Start process to create object records based on incoming webhooks" business process instead of the "Create object records based on incoming webhook". Out of the box, the "Create object records based on incoming webhook" business process is deactivated in Marketing Creatio product and Lead Generation composable app.

The "Create object records based on incoming webhook" business process attempts to parse the webhook to add a Creatio record. The business process works as follows out of the box:

1. Read a collection of new webhooks (50 records whose Status field value is "New") from the "Webhooks" dashboard list every minute.
2. Change the webhook status from "New" to "Processing."
3. Change the status of webhooks whose status remains "Processing" for longer than the specified period (1 hour by default) back to "New." It is a disaster recovery mechanism. Learn more: Wikipedia.
4. Create the record.

You can customize the business process or deactivate it and create a custom process. If you want to receive a webhook in Creatio without adding a record, deactivate the business process. For example, this is useful if you want to achieve the following:

• Set up a notification about new webhooks.
• Create a record based on the webhook.
• Send an email that contains webhook data.
• Set up a notification about a webhook processing error.

The "Create entity" user task (the "Webhook To Entity UT" task in the Configuration section) executes the main functionality of the "Create object records based on incoming webhooks" business process. The user task works as follows out of the box:

1. Define a parser for the webhook data type based on the Content type field value in the "Webhooks" dashboard list.
2. Define the object to add a record based on the webhook. Requires the EntityName parameter in the Request body field. Learn more about configuring the parameter: Work with webhooks basics.
3. Populate other fields of the record based on the parameters of the Request body field.
4. Save the record to Creatio.

If the incoming webhook does not contain the Content-Type or EntityName parameter value, the process cannot create the record based on a webhook. In this case, the webhook status is set to "Failed."

If the incoming webhook data differs from the expected data, the parsing fails. Creatio displays the errors for the dedicated webhook in the Parsing errors list on the webhook page. The process logs the detailed error in the Webhook parse errors log lookup and changes the webhook status to "Failed."

View the logged webhook processing errors in the table below.

Error text	Error description	Error correction
An error occurred while setting the column value. ColumnName:{ColumnName}. EntityName:{EntityName}. Exception:Cannot cast {ActualType} to {ExpectedType}.	The column data type of the incoming webhook does not match the column data type in the added Creatio object. The object is added, and the parsed columns are populated. The columns specified in the error are not populated. Webhook status is not changed to "Failed."	Verify the mapping of webhook columns to Creatio object columns. Learn more: Work with webhooks basics.
An error occurred while processing the webhook. Entity name: "{EntityName}" Exception: Item with name "{EntityName}" not found.	Unable to find the Creatio object specified in the EntityName webhook parameter.	Verify the object name in the external webhook service. Ensure the EntityName parameter value matches the object code. Learn more in a separate article: Work with webhooks basics.
An error occurred while processing the webhook. The parameter "{EntityName}" should be existing and not empty.	The EntityName webhook parameter does not exist or is empty.	Add or fill out the object code.
An error occurred while processing the webhook. Exception: The parameter "{Content-Type}" should be existing and not empty.	The Content-Type webhook parameter does not exist or is empty.	Verify the data type in the Content-Type webhook parameter. If the data type is populated, but the field name is different, contact Creatio support for a detailed analysis of the webhook service.
An error occurred while processing the webhook. Exception: {Content-Type} type of webhook is unsupported.	The data type listed in the Content-Type webhook parameter is unsupported. Creatio supports application/json and multipart/form-data data types of the webhook body.	Contact Creatio support.
An error occurred while processing the webhook. Exception: Could not parse the webhook body: {RequestBody}.	An unexpected error occurred when processing the RequestBody webhook parameter.	Contact Creatio support for a detailed analysis of the webhook.

Customize webhook processing

If you want to create a custom business logic of a webhook processing, modify the out-of-the-box business processes or create a new business process. We recommend deactivating out-of-the-box business processes instead of deleting them.

---

See also

Work with webhooks basics

Retrieve a webhook in Creatio

Data import

Tech Hour: Webhooks. Integrating with Landingi, Wordpress and MS Forms