This getting started article will help Administrators to create Webhooks in the TDAdmin console for a Ticket or Asset/CI application. The user must have the Administrator rights in TDAdmin.
Overview
TeamDynamix webhooks allow you to build additional types of integrations that would not be possible using the TeamDynamix API. Administrators can configure a webhook to send a message every time that a ticket, asset, or CI is created, modified, or deleted. This message will include metadata about the webhook event and the details of the ticket, asset, or CI (excluding deletes).
Where to Find This
The configuration for this is located in TDAdmin. Follow the steps below to configure the Webhooks accordingly in TeamDynamix.
Where to Start
Configuring Webhooks
To configure a webhook in a ticketing or asset/CI application:
- Enable Key-Based Web Services in TDAdmin if they are not already enabled.
- Navigate to TDAdmin > Security tab.
- Click Enable under Key-Based Web Services.
- Navigate to the Webhooks page in TDAdmin > Applications > [Ticket or Asset/CI application] > Webhooks.
- Click New to create a new webhook.
- Choose a Name. This will be used within TDAdmin to refer to the webhook but is not sent as part of the payload.
- Optionally provide a Description of what the webhook will be used for.
- Set the webhook to Active.
- Choose a Content Type. TeamDynamix webhooks support the
application/json and application/x-www-form-encoded content types. The receiving system will determine which one is appropriate to use.
- Choose the URL that the webhook will be sent to. This will be dependent on the system that you are interacting with. If you are integrating with TeamDynamix iPaaS, see this article for information about how to set up iPaaS to receive a webhook.
- Optionally choose a Secret. This is used to set the X-Tdx-Signature header, and can be used by the receiving system to validate that the webhooks have not been spoofed by an external system.
- Choose whether to enable SSL Verification. This makes the webhooks caller verify the recipients SSL certificate.
- Choose which Events to send with the webhook. Webhooks can be sent for tickets, assets, and CIs. For each item type, they can be sent for created, modified, and deleted events.
- Save. The webhook will being broadcasting create, modify, and delete events that occur after saving.
Webhook Triggers
The webhooks are triggered by monitoring the database tables for tickets, assets, or CIs and reacting to each database transaction. This means that any activity that modifies a ticket/asset/CI and therefore changes the Modified date will trigger the webhook event.
Webhook Content
Each webhook event will send an HTTP POST to the URL you specify.
Webhook messages will have the following headers:
- Request Method: POST
- Request URL: The URL you choose to send the webhook to
- X-Tdx-Signature: An SHA-1 HMAC hash of the payload using the Secret field in the webhook definition. This allows you to verify that the webhook call is legitimately sent from TeamDynamix.
The webhook body will be JSON with a metadata element that contains the type of webhook (Ticket, Asset, or CI), the ID of the affected item, and the change type (Created, Modified, Deleted) and a data element that contains the details of the ticket, asset or CI (except for deletes). The details will have the same content as provided by the GET Ticket, GET Asset, or GET Configuration Item endpoints in the TeamDynamix web API.
Reviewing Webhook Results in TDAdmin
Once a webhook has been configured and activated, it will begin sending the related events to the request URL. When building or monitoring integrations using webhooks, administrators may need to review the results of the webhook calls. This article describes how to view and filter the webhooks results and resend them if necessary.
To view webhook results, Administrators should:
- In TDAdmin, click Applications in the left navigation.
- Click the desired Application Name.
- Webhooks > Webhook name.
- view the details of a webhook execution by clicking in the Execution ID or Date columns. The Webhook Execution Details page will include the details of the webhook request and response, which can be used for troubleshooting.
- Filter the list of webhook executions using the filter button.
The Recent Executions section at the bottom of the webhook definition page will list the following information:
- Execution ID: The identifier of this webhook execution, which may be used for troubleshooting
- Item ID: The identifier for the ticket, asset, or CI that is referenced by the webhook.
- Event: The type of event
- Date: The date and time that the webhook was message was sent.
- Last Resend Date: The date and time that the webhook was most recently called.
- Status: The HTML status code or other text returned by the receiving system.
- Duration: The time in milliseconds from that it took to send the webhook request.
- Did Timeout?: Whether the webhook timed out.
- Resend: A button to re-send this specific execution.
Frequently Asked Questions
This article answers frequently asked questions about the webhooks system.
Can webhooks be used with objects other than tickets, assets and CIs?
Currently, only tickets, assets and CIs support webhooks. If you are looking to use webhooks in another area of the system, please submit an enhancement request.
If a webhook fails to send, is there a retry protocol?
If the webhook fails to send on our side, it will remain queued until it’s able to send. If the queue of unsent webhooks gets too long, the infrastructure team is alerted so we can figure out why they didn’t send.
Can you report on webhook history?
No. you can filter on the webhook history and export it to Excel, but there are not report builder reports for the webhook history.
How long is the webhook history kept?
The webhook history is kept for 30 days.
Will using webhooks make my system slower?
The process of calling a webhook happens asynchronously from the actions that trigger the webhook. This means that the webhooks system will not make it slower to work within TDNext or TDClient because the system is not waiting for the webhooks to process. However, the webhooks system does add some load to system resources, which we are continuing to monitor.
How do webhooks work when multiple items are created or updated at once?
The webhooks system applies to each item individually. Therefore if multiple items are updated at once (e.g. importing assets or cascading a ticket update from a problem to the child incidents), a webhook will be sent for each item.