Configure Webhook Actions
|
Outbound Webhooks Premium Feature Reach out to your Customer Success Manager or Account Executive to learn more about this feature. |
Administrators can set up outbound webhook actions to send record data to external systems as an event occurs in Case IQ. This allows organizations to configure case management workflows that proactively push data into their larger ecosystem, such as their HRIS systems, ticketing platforms, notification services or analytics tools.
How You Can Use Webhooks
Webhooks are a flexible integration tool that can connect Case IQ to hundreds of different applications. For example, you can configure webhooks to:
- Send notifications in your messaging service to your investigators when a new case has been added.
- Create a task in your project management system when a to-do is added to a case.
- Update an employee's record in HR information system when a Case IQ profile is updated.
Before you Begin...
- Confirm with your Case IQ Account Executive or Customer Success Manager that the outbound webhooks feature has been activated for your application.
- Make sure you have access to the system that will receive the information. You will need the receiving system's webhook endpoint URL, required HTTP method, and authentication credentials.
- Consider the information the receiving system needs. Does the system need all record information, just the record ID, or only a few record fields?
- Determine the event that should trigger Case IQ to send information. Should Case IQ send record information when a party is updated? Should it be triggered by a case workflow step?
1. Decide the Rule Type
You can configure outbound webhook actions for either a workflow or record event rule. Workflow rules will run when a case is moved to a certain step in a workflow, while record event rules are triggered when an action occurs to a record, such as a record being created or updated.
| Rule Type | Use it for webhooks when you need to: |
|---|---|
| Workflow |
|
| Record event |
|
-
To use a workflow
-
To use a record event rule
- Add Button
1. Navigate to Settings > Workflow. In the grid, click the workflow to use for the webhook.

2. Click the Edit button on the workflow's page.

3. Click the Rules tab.

4. You can now configure the webhook action. See the next section, Add the Webhook Action, for instructions.
1. Navigate to Settings > Workflow > Rules. To create a rule for the webhook action, click the Add Rule button. To use an existing rule, select it in the Rules grid. The "Rule Type" must be "Record Event".

2. If you are adding a rule, complete the following fields in the New Rule Form. If you are using an existing rule, skip to the next section in this article, Add the Webhook Action, to begin configuring your webhook action.
- Name: enter a descriptive name for your rule.
- Rule Type: select "Record Event".
- Record Type: select the record type to send to your external system, for example case, party, file, note, to-do, etc.
- Record Event: select the event that should trigger the rule. The available "Record Event" options depend on the record type you choose. For example, if you select the "party" record type, the rule's actions can be initiated when a party is created, updated, or deleted.
Case Record Events
If you select "Case" as the record type, the following additional record events will be displayed in the dropdown:
- Case Assignment: a case owner has been assigned.
- Case Cancelled: a previously open case has been cancelled.
- Case Closed: all workflows have been completed and the case is in a “Closed” status type.
- Case Linked: another case is linked to a case.
- Case Reopened: one or more of the previously closed workflows has been moved to an “open” status.
- Case Restored: a previously cancelled case is restored, removing the “cancelled” status.
- Case Updated: any edits to a case field or an action completed by a user on a case.
- New Case Submitted: a case is added into Case IQ.

3. In the Criteria section, you can set the conditions that the record must meet before the rule will be triggered. When the record event you selected occurs, the system will evaluate the rule's criteria and only run its actions if the criteria are met. If the rule should always be triggered when the record event occurs, skip adding criteria.
You can select the following criteria options for case rules:
- All Automatic Linked Cases must be Closed
- Case Owner must be assigned
- To-Dos must be Closed
- Must match the following custom criteria
For any other record type, you will only be able to set up custom criteria.
Creating Custom Criteria for a Rule
In Case IQ, custom criteria are similar to simple math equations, where a record field equals a certain value. The system will only run the rule when this equation is true for a record. For example, suppose you wanted a rule to trigger when a party's “Country” field is "America". The criteria would be: "Country" "Is" "America".
To create custom criteria for a rule:
- Click the “Must match the following custom criteria” checkbox in the Criteria section.
- Select one of the record type's fields in the "Search fields..." dropdown.
- More fields will be displayed in the row to finish the criteria. Select an operator in the next dropdown, such as "contains", "is", or "is not". The operator tells the system how to compare the field to the value. For example, if you select "Contains", the rule will be triggered when the field contains a certain value.
- Select or enter a value in the last field of the row. The system will check the field for this value to determine whether to trigger the rule.
- You will see different input methods to select a value based on the field's type. For example, if you choose a radio button field, you can select the value using radio buttons.
- If you select "Is Empty" or "Is Not Empty" as the operator, you do not need to select a value.
- Click the + Criteria button to create criteria with another field. Repeat steps 2 to 4 for the new row.
- If you have more than one criteria, use the "All / Or" toggle to set whether the record must meet all or one of the criteria.
- All: the rule will only run if all criteria are met.
- Or: the rule will run when at least one of your criteria are met.

Creating Criteria for Field Value Changes
For some record events, you can set a rule to run when the values of specific fields are updated with the “Must match the criteria only when the field change” criteria option. For example, you can set a rule to trigger when a case field called “Substantiated” is changed. “Must match the criteria only when the field change” will only be available for the following record events on standalone rules:
- Case: assignment, cancelled, restored, and updated.
- Appointment: cancelled, saved, sent, and updated.
- File: updated.
- Note: updated.
- Party: updated.
- Profile: updated.
- Request: cancelled, completed, declined, expired, failed delivery, resent, and updated.
- To-do: completed, and updated.
To use field changes as rule criteria:
- Click the “Must match the criteria only when the field change” checkbox in the Criteria section.
- Select one of the record type's fields in the "Fields to Watch" dropdown.
- If you select multiple fields, use the "All / Any" toggle to set whether the rule will be triggered when all or one of the fields is changed.
- All: the rule will only run if all fields are changed.
- Or: the rule will run when at least one of the fields is changed.

4. You can now configure the webhook action. See the next section, Add the Webhook Action, for instructions.
2. Add the Webhook Action
When you have completed filling in the New Rule form, you can set up your webhook action using the following steps:
1. In the Actions section, click the "+" button. Then, select "Add Webhook".

2. Complete the following fields in the New Webhook form:
- Trigger Type: choose to send the webhook immediately or on a delay.
- After selecting “Delay”, you can choose how long after the criteria have been met to send the webhook. In the “Delay” fields, enter a number and the unit of time (i.e. minutes, hours, and calendar days) to control when the action will be carried out by the system.
- For example, if you choose “5” and “days”, the webhook will be sent 5 calendar days after the rule was triggered if the rule criteria are still true.
- Endpoint: enter the endpoint URL provided by your external system, which tells Case IQ where to send the record data.
- HTTP Method: choose if Case IQ should send a POST, PUT, PATCH, or DELETE request to send data from the external system. Select the HTTP method based on your external system's requirements.
- Authentication Method: select how your external system authenticates requests from the following options: “None”, “Basic Auth”, "Bearer Token", or “OAuth Client Credential”.
Basic Authentication
If you select “Basic Auth”, the “Username” and “Password” fields will be displayed, so you can enter the username and password that your external system uses to authenticate requests. The username and password must match those expected by your external system for requests to be permitted.
After you enter the username and password, you can click the Test Authentication button below the "Password" field to check your settings. This allows Case IQ to check for any 401 Unauthorized errors.
DeleteBearer Token
If you select "Bearer Token", you can enter the bearer token provided by your external system to authenticate requests. The token must match the string expected by your external system.
After entering your bearer token, you can click the Test Authentication button below the "Password" field to check your settings. This allows Case IQ to check for any 401 Unauthorized errors.
DeleteOAuth Client Credential
If you select “OAuth Client Credential”, you will see the following additional fields to configure the authentication:
- Access Token Endpoint: enter the URL from which Case IQ should obtain the secure token, e.g https://{yourDomain}/oauth/token.
- Client ID: enter the ID provided by your external system.
- Client Secret: enter the secret value provided by your external system.
- Client Authentication Option: choose how Case IQ should send the credentials from the following options:
- Body: Case IQ will include a body in the authentication request following the headers.
- Basic Authentication Header: the "Client ID" and "Client Secret" will be encoded in base64 format, then passed as an HTTP header to the external system, e.g. Authorization: Basic {value}
- Scope: if required by your external system, define any permissions Case IQ needs.
After you enter the required OAuth fields, you can click the Test Authentication button below the "Scope" field to check your settings. This allows Case IQ to check for any 401 Unauthorized errors.
DeleteOAuth Password Grant
If you select “OAuth Password Grant”, you will see the following additional fields to configure the authentication:
- Username: enter the username your external system uses to authenticate requests.
- Password: enter the password your external system uses to authenticate requests.
- Access Token Endpoint: enter the URL from which Case IQ should obtain the secure token, e.g https://{yourDomain}/oauth/token.
- Client ID: enter the ID provided by your external system.
- Client Secret: enter the secret value provided by your external system.
- Client Authentication Option: choose how Case IQ should send the credentials from the following options:
- Body: Case IQ will include a body in the authentication request following the headers.
- Basic Authentication Header: the "Client ID" and "Client Secret" will be encoded in base64 format, then passed as an HTTP header to the external system, e.g. Authorization: Basic {value}
- Scope: if required by your external system, define any permissions Case IQ needs.
After you enter the required OAuth fields, you can click the Test Authentication button below the "Scope" field to check your settings. This allows Case IQ to check for any 401 Unauthorized errors.
Delete- Payload: choose how much record data is included in the webhook by selecting one of the following payload modes:
- Default: all record information.
- ID only: only the record ID.
- Advanced: define the payload with an ISEL expression.
Webhook Request Format
Every webhook request includes an outer JSON object with these properties:
- type: the event identifier shown in the action's Event Type field.
- timestamp: the UTC time when the delivery request is prepared. This is not the time the original record event occurred.
- data: the record data selected by the Payload setting.
For example, an "ID Only" payload for a party update will have the following shape. The example values are illustrative.
{
"type": "party.entity_updated",
"timestamp": "2026-11-11T15:00:00.000Z",
"data": {
"id": "record-id"
}
}
Setting the payload to "ID Only" or "Advanced" changes the contents of "data", but the request will still include the "type" and "timestamp".
For workflow webhooks, the event identifier is saved when the webhook action is first saved. Renaming the workflow or step later does not change that identifier.
DeleteAdvanced Payload Examples
You could use the following expression to only include the case's ID, number, and status in the payload. This expression will also populate the case's source as "Case IQ" and, if the case's type is "HR", set it to high priority in the external system.
{
caseId: case.id,
caseNumber: case.caseNumber,
status: case.status,
source: 'Case IQ',
highPriority: case.caseType == 'HR'
}
Similarly, this expression will include the case's ID, number, type, and date recorded in the payload. If the case's type is "Investigation", the case's priority will be set to high in the external system.
{
id: case.id,
number: case.caseNumber,
type: case.caseType,
recordedOn: case.dateRecorded,
priorityLabel: case.caseType == 'Investigation' ? 'High' : 'Normal',
}
Delete
3. When you have finished configuring the webhook action, click the Save button in the New Webhook section. Make sure to save the action before saving the rule.

4. After saving the action, save the rule. For a record event rule, the Save button is at the top of the page. For a workflow rule, click the Save button in the New Rule section.

5. If you added the webhook action to a workflow, save your changes to the workflow. Then, publish the workflow.

3. Verify the Webhook Rule Configuration
After saving your webhook action and rule, we recommend verifying delivery with a test record and manually triggering the rule. Manually running a rule will execute all the rule's actions. Check if the rule has multiple actions before proceeding.
To test a webhook configuration:
1. Create a test record in Case IQ that meets your rule's criteria.
2. Navigate to the webhook rule's page. Click the Options (
) button and select "Run Rule".

3. Check if your external system received the record.
4. Check the webhook audit log in Case IQ. Navigate to the case’s History tab and click the Actions sub-tab. Logs will include the authentication method, HTTP method, endpoint, payload mode, and response status (e.g. 200 OK or 503 Service Unavailable). Case IQ does not store the authentication headers or full request or response bodies. The system will only attempt webhook delivery once.

5. To run the webhook again, click the row in the Actions grid. The rule's page will be loaded, so you can manually run the rule again.
4. Set Up Failure Notifications
You can set up Case IQ notifications in the event webhook delivery fails. A notification will be sent once per endpoint and failure type (error code) every 8 hours. By default, Case IQ will not alert you if a webhook action fails. To set up these notifications:
1. Navigate to Settings > Workflow > Rules. Click the "Webhook Failed" rule. This rule will be available by default when the outbound webhooks feature is activated for your application.

2. In the Actions section, click the Notification row.

3. Click the Edit button in the Notification section. This notification action is preconfigured with a message template. You can set who will receive this notification and adjust the message as needed.

4. You can now update the notification action. Complete the following fields in the Triggers section:
- Trigger Type: "Immediate" is the only available trigger type for this rule, meaning the webhook failed notification will be sent immediately.
- Method: by default, Case IQ will send the notification by email. If a Twilio integration has been set up for your application, you can also choose to send notifications via SMS or phone (see Twilio Integration for details).
5. In the Distribution section, you can use any of the following fields to choose who will receive the notification:
- Include System User Roles: send the notification to all users with a specific user role. For example, you could send a notification to all users with the "Super User" role.
- Include System Users: select specific users to which to send notifications.
- Include Teams: select any teams in Case IQ who should receive the notification.
- Include Other Addresses: type in email addresses to send the notification to people who are not Case IQ users.

6. In the Content section, review the default notification message and make adjustments to the following fields as needed:
- High Priority: check to send the email notification with high priority based on the recipient’s email browser.
- Subject: the subject line for the email notification.
- Template: the message sent to recipients. This template contains placeholder text, called “tags”, that Case IQ will replace with contextual information about the webhook failure when the notification is sent, e.g. {webhook.endpoint} and {webhook.responseStatus}.

7. When you have finished adjusting the notification action, click the Save button in the Edit Notification section. Make sure to save the action before saving the rule.

8. Click the Options (
) button at the top of the page. Then, select "Activate".

5. Troubleshooting
If a webhook does not work as expected, start by reviewing the rule settings and checking the receiving system.
- Check that the rule is active or that workflow changes were published.
- Make sure the record meets the rule's criteria. If the action has a delay, allow time for it to run.
- Check that the endpoint, HTTP method, authentication, and payload match the receiving system's requirements.
- Review the delivery status in the case's History > Actions tab, where available.
- Ask the receiving system's administrator to check its logs and confirm whether the data was received and processed.
- If failure notifications are missing, check that the Webhook Failed rule is active and has the correct recipients.
Action History shows delivery details but does not include full request or response bodies. The receiving system's logs may provide more information about an error.
Case IQ does not automatically retry failed webhook deliveries. After fixing the issue, check whether the receiving system already processed the request before using Run Rule. This runs all the rule's actions again and may repeat their effects.