Webhooks

Jump to:

The Ticketing API supports push notifications through webhook subscriptions, enabling real‑time delivery of case‑related events to customer‑defined endpoints.

You have full control over your webhook subscriptions, including the ability to subscribe exclusively to new case creation events, or subscribe to both case creation and subsequent case updates.

Webhook endpoints and associated authentication credentials can be configured, updated, and refreshed programmatically using the API methods described below. This allows for fully automated lifecycle management of webhook integrations, ensuring alignment with customer security, availability, and operational requirements.

Set up subscription

This endpoint registers a new webhook subscription for a specific namespace. By creating a webhook, your system can receive real-time HTTP callbacks (POST or PUT requests) whenever a specific action occurs on a specific case within that namespace.

Feature	Details
Method	POST
Endpoint	/apis/v1/namespaces/{namespace}/webhook

Path parameters

Parameter	Type	Required	Description
namespace	String	Yes	The unique identifier for the namespace. (e.g., 7 in the example)

Headers

Header	Value	Required	Description
Authorization	Bearer <TOKEN>	Yes	A valid API Bearer token for authentication
Content-Type	application/json	Yes	Specifies the media type of the resource (standard for JSON APIs)

Request body

The request body is divided into standard metadata and a spec object containing the endpoint details. Please note that you can set different endpoints for actions “create” and “update”, they need to be executed separately in any scenario. Action “delete” will unsubscribe you from the selected webhook subscription.

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “webhook”
version		String	Yes	Set value “v1”
namespace		String	Yes	Must match the {namespace} in the URL
name		String	Yes	A unique, user-defined name for this specific webhook configuration. Needs to be different for the different “action” values – create and update. Please store the “name” as you will need it to update the subscription when needed.
metadata		Object	Yes	Empty object {}
spec		Object	Yes	The specification object contains detailed information
	url	String	Yes	The destination URL (endpoint) where the event payload will be sent
	version	String	Yes	Set value “v1alpha”
	kind	String	Yes	Set value “case”
	action	String	Yes	The specific lifecycle event that triggers the webhook. Possible values: create, update
	credential	Object	Yes	Credentials associated with the endpoint
	type	String	Yes	Set value “basic”
	secrets	Object	Yes	Basic authentication object
	type	String	Yes	Set value “plaintext”
	values	Object	Yes	User and Password object
	value	String	Yes	Username that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “username”
	value	String	Yes	Password that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “password”

Response body

The response will mirror your subscription with filled “metadata” for the webhooks creation.

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “webhook”
version		String	Yes	Set value “v1”
namespace		String	Yes	The ID of the {namespace} the case belongs to
name		String	Yes	The unique identifier you have given the webhook
metadata		Object	Yes	A key-value map for additional custom data
spec		Object	Yes	The specification object contains detailed information
	url	String	Yes	The destination URL (endpoint) where the event payload will be sent
	credential	Object	Yes	Credentials associated with the endpoint
	type	String	Yes	Set value “basic”
	url	String	Yes	Set value “null”. URL link to your credentials
	secrets	Object	Yes	Basic authentication object
	type	String	Yes	Set value “plaintext”
	values	Object	Yes	User and Password object
	value	String	Yes	Username that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “username”
	value	String	Yes	Password that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “password”
	version	String	Yes	Set value “v1alpha”
	kind	String	Yes	Set value “case”
	action	String	Yes	The specific lifecycle event that you have subscriber for. Possible values: create, update

Example request

curl--location--request POST 'https://test.api.gtt.services/apis/v1/namespaces/7/webhook'\
    --header 'Content-Type: application/json'\
    --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
    --body {
        "kind": "webhook",

        "version": "v1",
        "namespace": "7",
        "name": "case-v1alpha-create",
        "metadata": {},
        "spec": {
            "url": "https://testendpoint.net/create",
            "version": "v1alpha",
            "kind": "case",
            "action": "create",
            "credential": {
                "type": "basic",
                "secrets": {
                    "type": "plaintext",
                    "values": [{
                            "value": "myusername",
                            "name": "username"
                        },
                        {
                            "value": "mypassword",
                            "name": "password"
                        }
                    ]
                }
            }
        }

Example response (success)

{
    "kind": "webhook",
    "version": "v1",
    "namespace": "7",
    "name": "case-v1alpha-create",
    "metadata": {
        "dateCreated": 1777016997284,
        "dateUpdated": 1777016997284
    },
    "spec": {
        "url": "https://testendpoint.net/create",
        "credential": {
            "type": "basic",
            "url": null,
            "secrets": {
                "type": "plaintext",
                "values": [{
                        "value": "myusername",
                        "name": "username"
                    },

                    {
                        "value": "mypassword",
                        "name": "password"
                    }
                ]
            }
        },
        "version": "v1alpha",
        "kind": "case",
        "action": "create"
    }
}

Update subscription

This action will allow you to change the URL and/or credentials to your webhook subscriptions.

Please note that you will need the “name” of the subscription to execute an update.

Feature	Details
Method	PUT
Endpoint	/apis/v1/namespaces/{namespace}/webhook/{name}

Path parameters

Parameter	Type	Required	Description
namespace	String	Yes	The unique identifier for the namespace. (e.g., 7 in the example)
name	String	Yes	The unique “name” identifier you have given the webhook during subscription set up

Headers

Header	Value	Required	Description
Authorization	Bearer <TOKEN>	Yes	A valid API Bearer token for authentication
Content-Type	application/json	Yes	Specifies the media type of the resource (standard for JSON APIs)

Request body

The request body is divided into standard metadata and a spec object containing the endpoint details. Please note that you can set different endpoints for actions “create” and “update”, they need to be executed separately in any scenario. Action “delete” will unsubscribe you from the selected webhook subscription.

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “webhook”
version		String	Yes	Set value “v1”
namespace		String	Yes	Must match the {namespace} in the URL
name		String	Yes	The unique “name” identifier you have given the webhook during subscription set up
metadata		Object	Yes	Empty object {}
spec		Object	Yes	The specification object contains detailed information
	url	String	Yes	The destination URL (endpoint) where the event payload will be sent
	version	String	Yes	Set value “v1alpha”
	kind	String	Yes	Set value “case”
	action	String	Yes	The specific lifecycle event that triggers the webhook. Possible values: create, update, delete
	credential	Object	Yes	Credentials associated with the endpoint
	type	String	Yes	Set value “basic”
	secrets	Object	Yes	Basic authentication object
	type	String	Yes	Set value “plaintext”
	values	Object	Yes	User and Password object
	value	String	Yes	Username that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “username”
	value	String	Yes	Password that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “password”

Response body

The response will mirror your subscription update with filled “metadata” for the webhooks.

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “webhook”
version		String	Yes	Set value “v1”
namespace		String	Yes	The ID of the {namespace} the case belongs to
name		String	Yes	The unique identifier you have given the webhook
metadata		Object	Yes	A key-value map for additional custom data
spec		Object	Yes	The specification object contains detailed information
	url	String	Yes	The destination URL (endpoint) where the event payload will be sent
	credential	Object	Yes	Credentials associated with the endpoint
	type	String	Yes	Set value “basic”
	url	String	Yes	Set value “null”. URL link to your credentials
	secrets	Object	Yes	Basic authentication object
	type	String	Yes	Set value “plaintext”
	values	Object	Yes	User and Password object
	value	String	Yes	Username that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “username”
	value	String	Yes	Password that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “password”
	version	String	Yes	Set value “v1alpha”
	kind	String	Yes	Set value “case”
	action	String	Yes	The specific lifecycle event that you have subscriber for. Possible values: create, update, delete

Example request

curl--location--request PUT 'https://test.api.gtt.services/apis/v1/namespaces/7/webhook/case-v1alpha-create'\
    --header 'Content-Type: application/json'\
    --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'
    --body {
        "kind": "webhook",
        "version": "v1",
        "namespace": "7",
        "name": "case-v1alpha-create",
        "metadata": {},
        "spec": {
            "url": "https://testendpoint.net/create",
            "version": "v1alpha",
            "kind": "case",
            "action": "create",
            "credential": {
                "type": "basic",
                "secrets": {
                    "type": "plaintext",
                    "values": [{
                            "value": "myusername2",
                            "name": "username"
                        },
                        {
                            "value": "mypassword2",
                            "name": "password"
                        }
                    ]
                }
            }
        }
    }

Example response (success)

{
    "kind": "webhook",
    "version": "v1",
    "namespace": "7",
    "name": "case-v1alpha-create",
    "metadata": {
        "dateCreated": 1777016997284,
        "dateUpdated": 1777016997284
    },
    "spec": {
        "url": "https://testendpoint.net/create",
        "credential": {
            "type": "basic",

            "url": null,
            "secrets": {
                "type": "plaintext",
                "values": [{
                        "value": "myusername2",
                        "name": "username"
                    },
                    {
                        "value": "mypassword2",
                        "name": "password"
                    }
                ]
            }
        },
        "version": "v1alpha",
        "kind": "case",
        "action": "create"
    }
}

List webhook subscriptions

This call will retrieve all your subscriptions for webhooks associated to a specific namespace.

Feature	Details
Method	GET
Endpoint	/apis/v1/namespaces/{namespace}/webhook

Path parameters

Parameter	Type	Required	Description
namespace	String	Yes	The unique identifier for the namespace. (e.g., 7 in the example)

Headers

Header	Value	Required	Description
Authorization	Bearer <TOKEN>	Yes	A valid API Bearer token for authentication
Content-Type	application/json	Yes	Specifies the media type of the resource (standard for JSON APIs)

Response body

The response will mirror your subscription update with filled “metadata” for the webhooks.

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “webhook”
version		String	Yes	Set value “v1”
namespace		String	Yes	The ID of the {namespace} the case belongs to
name		String	Yes	The unique identifier you have given the webhook
metadata		Object	Yes	A key-value map for additional custom data
spec		Object	Yes	The specification object contains detailed information
	url	String	Yes	The destination URL (endpoint) where the event payload will be sent
	credential	Object	Yes	Credentials associated with the endpoint
	type	String	Yes	Set value “basic”
	url	String	Yes	Set value “null”. URL link to your credentials
	secrets	Object	Yes	Basic authentication object
	type	String	Yes	Set value “plaintext”
	values	Object	Yes	User and Password object
	value	String	Yes	Username that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “username”
	value	String	Yes	Password that GTT will use for Basic authentication, associated with the URL
	name	String	Yes	Set value “password”
	version	String	Yes	Set value “v1alpha”
	kind	String	Yes	Set value “case”
	action	String	Yes	The specific lifecycle event that you have subscriber for. Possible values: create, update

Example request

curl --location --request GET 'https://test.api.gtt.services/apis/v1alpha/namespaces/7/webhook' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Example response (success)

[{
        "kind": "webhook",
        "version": "v1",
        "namespace": "7",
        "name": "case-v1alpha-create",
        "metadata": {
            "dateUpdated": 1777032490395
        },
        "spec": {
            "url": "https://testendpoint.net/create",
            "credential": {
                "type": "basic",
                "url": null,
                "secrets": {
                    "type": "plaintext",
                    "values": [{
                            "value": "myusername",
                            "name": "username"
                        },
                        {
                            "value": "mypassword",

                            "name": "password"
                        }
                    ]
                }
            },
            "version": "v1alpha",
            "kind": "case",
            "action": "craeted"
        }
    },
    {
        "kind": "webhook",
        "version": "v1",
        "namespace": "7",
        "name": "case-v1alpha-update",
        "metadata": {
            "dateUpdated": 1777032448975
        },
        "spec": {
            "url": "https://testendpoint.net/update",
            "credential": {
                "type": "basic",
                "url": null,
                "secrets": {
                    "type": "plaintext",
                    "values": [{
                            "value": "myusername",
                            "name": "username"
                        },
                        {
                            "value": "mypassword",
                            "name": "password"
                        }
                    ]
                }
            },
            "version": "v1alpha",
            "kind": "case",
            "action": "update"
        }
    }
]

Case create webhook

When a new case is created within your namespace, the system automatically triggers a webhook notification to your customer‑configured endpoint using a standard HTTP POST request.

The webhook payload exposes a defined set of case attributes that enable you to apply filtering, routing, or downstream processing logic based on business requirements. These attributes may be used to selectively process cases by characteristics such as:

Case type (e.g., Incident or Request)
Channel indicator, which allows you to distinguish cases generated by automated GTT monitoring systems from those created through other sources.

This capability enables you to control which cases are ingested, acted upon, or propagated within your own system.

Please note that cases created by you through the Ticketing API will NOT generate case creation webhook events. This behaviour is intentional to prevent event loops and duplicate processing within the integration.

Feature	Details
Method	POST
Endpoint	Your specified endpoint

Webhook body

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “case”
version		String	Yes	Set value “v1alpha”
namespace		String	Yes	Your {namespace} ID
name		String	Yes	A unique system identifier for the case record
metadata		Object	Yes	Empty object {}
spec		Object	Yes	The specification object contains detailed information
	number	String	Yes	The human-readable case number (e.g., “CS0071728”)
	state	String	Yes	The current lifecycle status of the case (e.g., “New”)
	case_type	String	Yes	Is the case of type Incident or Request
	channel	String	Yes	The channel which initiated the case opening. Table provided in the Appendix
	subcategory	String	Yes	A specific classification of the issue (e.g., “Service Down”). Table provided in the Appendix
	customer_ticket_reference	String	No	An optional reference ID provided by the customer for their internal tracking (can be null)
	account_name	String	Yes	The name of the customer account associated with the case
	gnid	String	Yes	The unique GTT Global Identifier for the service
	opened_at	String	Yes	Timestamp of when the case was created in UTC. (Format: YYYY-MM-DD HH:MM:SS)
	priority	String	Yes	The priority in which the case is handled (e.g., “1 – Critical”) Table provided in the Appendix
	short_description	String	Yes	Short Description of the issue
	description	String	Yes	A detailed description of the issue, often including error messages, Service IDs, or hostnames

Example POST

{
    "kind": "case",
    "version": "v1alpha",
    "namespace": "7",
    "name": "CS0148471",
    "metadata": {},
    "spec": {
        "number": "CS0148471",
        "state": "New",
        "case_type": "Incident",

        "channel": "Phone",
        "subcategory": "Service Down",
        "customer_ticket_reference": "",
        "account_name": "Sample Customer",
        "gnid": "1234567",
        "opened_at": "2026-04-02 11:50:40",
        "priority": "1 - Critical",
        "short_description": "Customer site unreachable",
        "description": "Ping timeout to CE router"
    }
}

Case update webhook

When an existing case is updated within your namespace, the system automatically triggers a webhook notification to your customer‑configured endpoint using a standard HTTP PUT request.

The webhook payload exposes a defined set of case attributes including any work notes (comments) added to the case.

Please note that comments created by you through the Ticketing API will NOT generate case update webhook events. This behaviour is intentional to prevent event loops and duplicate processing within the integration.

There is different structure of the body of the webhooks depending on the state in which the GTT case is in.

Payload when case is worked on. State can be = “New” or “In Progress” or “Pending” or “Force Majeure” or “Monitoring”.
Payload when case state is Resolved.
Payload when case state is Closed.
Payload when case state is Cancelled.

Case is worked on

The majority of notifications will come to you in this format, payload includes all fields that have a possibly of changing throughout the case life.

Feature	Details
Method	PUT
Endpoint	Your specified endpoint

Webhook body

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “case”
version		String	Yes	Set value “v1alpha”
namespace		String	Yes	Your {namespace} ID
name		String	Yes	A unique system identifier for the case record
metadata		Object	Yes	Empty object {}
spec		Object	Yes	The specification object contains detailed information
	number	String	Yes	The human-readable case number (e.g., “CS0071728”)
	state	String	Yes	The current lifecycle status of the case (e.g., “Pending”)
	subcategory	String	Yes	A specific classification of the issue (e.g., “Service Down”)
	customer_ticket_reference	String	No	An optional reference ID provided by the customer for their internal tracking (can be null)
	gnid	String	Yes	The unique GTT Global Identifier for the service.
	priority	String	Yes	The priority in which the case is handled (e.g., “1 – Critical”) Table provided in the Appendix
	due_date	String	Yes	Timestamp of the next action date for the case update in UTC. (Format: YYYY-MM-DD HH:MM:SS)
	escalation_level	String	Yes	The current escalation level that the case is in (e.g., “1”). Table provided in the Appendix
	additional_comment	String	Yes	Text of the posted update
	additional_comment_author	String	Yes	User that added the update
	additional_comment_date	String	Yes	Date and time update was created in UTC. (Format: YYYY-MM-DD HH:MM:SS)

Example PUT

{
    "kind": "case",
    "version": "v1alpha",
    "namespace": "7",
    "name": "CS0148471",
    "metadata": {},
    "spec": {
        "number": "CS0148471",
        "state": "Pending",
        "subcategory": "Service Down",
        "customer_ticket_reference": "XYZ1235",
        "gnid": "1234567",
        "priority": "1 - Critical",
        "due_date": "2026-04-03 13:00:00",
        "escalation_level": "None",
        "additional_comment": "Please provide picture of equipment...",
        "additional_comment_author": "gtt.test.user",
        "additional_comment_date": "2026-04-02 11:59:30"
    }
}

Case is resolved

When your case is resolved by an engineer, you will receive a notification with “State = Resolved” and resolution details. In very specific cases it’s possible to receive this notification more than once with different additional comments, but the same resolution.

Feature	Details
Method	PUT
Endpoint	Your specified endpoint

Webhook body

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “case”
version		String	Yes	Set value “v1alpha”
namespace		String	Yes	Your {namespace} ID
name		String	Yes	A unique system identifier for the case record
metadata		Object	Yes	Empty object {}
spec		Object	Yes	The specification object contains detailed information
	number	String	Yes	The human-readable case number (e.g., “CS0071728”)
	state	String	Yes	The current lifecycle status of the case (e.g., “Resolved”)
	customer_ticket_reference	String	No	An optional reference ID provided by the customer for their internal tracking (can be null)
	work_end	String	Yes	Date and time in which the issue was resolved in UTC. (Format: YYYY-MM-DD HH:MM:SS). Time is in the past.
	close_notes	String	Yes	Resolution summary
	resolved_by	String	Yes	User that provided the resolution
	resolution_code	String	Yes	Resolution categorization – provided only for cases of type Request (e.g., “Successful”) Table provided in the Appendix
	additional_comment	String	No	Text of the posted additional comment. Can be blank

Example PUT

{
    "kind": "case",
    "version": "v1alpha",
    "namespace": "7",
    "name": "CS0148471",
    "metadata": {},
    "spec": {
        "number": "CS0148471",
        "state": "Resolved",
        "customer_ticket_reference": "XYZ1235",
        "work_end": "2026-04-03 12:01:00",
        "close_notes": "Resolution details",
        "resolved_by": "gtt.test.user",
        "additional_comment": ""
    }
}

Case is closed

After your case is resolved it will automatically close, within the time period outlined in the Case Statuses table in the Appendix. Once a case is closed it cannot be reopened or updated. You will receive this notification only once per case.

Feature	Details
Method	PUT
Endpoint	Your specified endpoint

Webhook body

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “case”
version		String	Yes	Set value “v1alpha”
namespace		String	Yes	Your {namespace} ID
name		String	Yes	A unique system identifier for the case record
metadata		Object	Yes	Empty object {}
spec		Object	Yes	The specification object contains detailed information
	number	String	Yes	The human-readable case number (e.g., “CS0071728”)
	state	String	Yes	The current lifecycle status of the case (e.g., “Closed”)
	customer_ticket_reference	String	No	An optional reference ID provided by the customer for their internal tracking (can be null)
	work_end	String	Yes	Date and time in which the issue was resolved in UTC. (Format: YYYY-MM-DD HH:MM:SS). Time is in the past.
	close_notes	String	Yes	Resolution summary
	resolution_code	String	Yes	Resolution categorization – provided only for cases of type Request (e.g., “Successful”) Table provided in the Appendix

Example PUT

{
    "kind": "case",
    "version": "v1alpha",
    "namespace": "7",
    "name": "CS0148471",
    "metadata": {},
    "spec": {
        "number": "CS0148471",
        "state": "Closed",
        "customer_ticket_reference": "XYZ1235",
        "work_end": "2026-04-03 12:01:00",
        "close_notes": "Resolution details"
    }
}

Case is cancelled

If your case is cancelled, it cannot be reopened. Case cancellation really occurs, typically if the case is opened with the wrong type, or if it’s a duplicate.

Feature	Details
Method	PUT
Endpoint	Your specified endpoint

Webhook body

Field	NESTED PROPERTY	Type	Required	Description
kind		String	Yes	Set value “case”
version		String	Yes	Set value “v1alpha”
namespace		String	Yes	Your {namespace} ID
name		String	Yes	A unique system identifier for the case record
metadata		Object	Yes	Empty object {}
spec		Object	Yes	The specification object contains detailed information
	number	String	Yes	The human-readable case number (e.g., “CS0071728”)
	state	String	Yes	The current lifecycle status of the case (e.g., “Cancelled”)
	customer_ticket_reference	String	No	An optional reference ID provided by the customer for their internal tracking (can be null)
	close_notes	String	Yes	Cancellation reason. Can be blank.

Example PUT

{
    "kind": "case",
    "version": "v1alpha",
    "namespace": "7",
    "name": "CS0148472",

    "metadata": {},
    "spec": {
        "number": "CS0148472",
        "state": "Cancelled",
        "customer_ticket_reference": "",
        "close_notes": "Duplicated of case CS0148471"
    }
}

Our People & Expertise

How can we help you?

Connect

Secure

Simplify

Services

Industries

Finance & Insurance

Manufacturing

Public Sector

Retail & E-commerce

Wholesale

Creating Greater Technology Together

Sharing our expertise with you

Webhooks

Set up subscription

Path parameters

Headers

Request body

Response body

Example request

Example response (success)

Update subscription

Path parameters

Headers

Request body

Response body

Example request

Example response (success)

List webhook subscriptions

Path parameters

Headers

Response body

Example request

Example response (success)

Case create webhook

Webhook body

Example POST

Case update webhook

Case is worked on

Webhook body

Example PUT

Case is resolved

Webhook body

Example PUT

Case is closed

Webhook body

Example PUT

Case is cancelled

Webhook body

Example PUT