v1

Webhook Basics¶

Webhooks provide an automated mechanism for delivering real-time updates directly to your ticketing system. Each message’s content varies based on the specific event that has occurred, ensuring you receive relevant and actionable information.

With webhooks, you gain immediate ticket updates, allowing for seamless integration and processing within your own systems without the need to continuously poll the Cyderes TSI API.

For enabling webhook functionality in your environment, please contact your Customer Success Manager (CSM) with the information outlined below.

Types of Events¶

There are four actions that trigger a webhook:

Action	Trigger
Escalate	A ticket has been escalated (Ticket creation event)
Update	A ticket has been updated
Comment	A comment has been added or updated
Attachment	An attachment has been added

Payloads¶

Escalate Event Field Terminology¶

Field	Description
action	The event action (comment, attachment, update, or escalate)
ticket_id	The unique id for the ticket
event_timestamp	The timestamp of when the message was sent
data	The action-specific data for the event
id	The unique id for the ticket
type	The type of ticket (i.e. "Service Task", "Phishing", "Alert")
escalated	A flag to determine if the ticket has been marked as escalated
priority	The priority of the issue represented as an integer (1-3)
status	The status of the ticket in Cyderes's internal system
created_at	The timestamp of when the ticket was created
updated_at	The timestamp of when the ticket was updated
analyst_notes	The analyst's notes regarding the ticket
recommendations	The analyst's recommended actions regarding the ticket
short_description	A short description of the ticket
description	An explanation of the ticket
soar_references	References to Cyderes's SOAR
insights	The Cyderes insights for this issue
raw_event_description	The Cyderes raw case alert payload

Example Escalate Event Payload¶

{
    "action": "escalate",
    "ticket_id": "CYDERES-XXXXXX",
    "event_timestamp": "1677614794",
    "data": {
        "ticket": {
            "id": "CYDERES-XXXXXX",
            "type": "Alert",
            "short_description": "PUBLIC_IP_ADDRESS Example",
            "description": "",
            "escalated": true,
            "priority": 3,
            "status": "In-Progress",
            "created_at": "2022-12-31T00:00:00Z",
            "updated_at": "2022-12-31T12:00:00Z",
            "analyst_notes": "This is where an analyst can leave their notes.",
            "recommendations": "This is where an analyst can leave their recommendations",
            "soar_references": {
                "case_id": "XXXXXXX",
                "alert_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
            },
            "insights": {
                "html_format": "",
                "json_format": ""
            },
            "raw_event_description": "[{}]"
        },
        "comments": [
            {
                "id": "XXXXX",
                "author": "Jane Smith",
                "body": "This is the comment body. It is the text of the comment.",
                "created_at": "2022-12-31T00:00:00Z"
            }
        ],
        "attachments": [
            {
                "id": "XXXXX",
                "file_name": "screenshot.png",
                "created_at": "2022-12-31T00:00:00Z",
            }
        ]
    }
}

Comment Event Field Terminology¶

Field	Description
action	The event action (comment, attachment, update, or escalate)
ticket_id	The unique id for the ticket
event_timestamp	The timestamp of when the message was sent
data	The action-specific data for the event
id	The unique id for the comment
author	The name of the comment author
body	The comment text content
created_at	The timestamp of when the comment was created

Example Comment Event Payload¶

{
    "action": "comment",
    "ticket_id": "CYDERES-XXXXXX",
    "event_timestamp": "1677614794",
    "data": {
        "comment": {
            "id": "XXXXX",
            "author": "Jane Smith",
            "body": "This is the comment body. It is the text of the comment.",
            "created_at": "2022-12-31T00:00:00Z"
        }
    }
}

Attachment Event Field Terminology¶

Field	Description
action	The event action (comment, attachment, update, or escalate)
ticket_id	The unique id for the ticket
event_timestamp	The timestamp of when the message was sent
data	The action-specific data for the event
id	The unique id for the attachment
file_name	The file name of the attachment
created_at	The timestamp of when the attachment was created

Example Attachment Event Payload¶

{
    "action": "attachment",
    "ticket_id": "CYDERES-XXXXXX",
    "event_timestamp": "1677614794",
    "data": {
        "attachment": {
            "id": "XXXXX",
            "file_name": "screenshot.png",
            "created_at": "2022-12-31T00:00:00Z"
        }
    }
}

Note: A call to our API using the attachment_id is needed to get the body of the attachment. Click here or more information.

Update Event Field Terminology¶

Field	Description
action	The event action (comment, attachment, update, or escalate)
ticket_id	The unique id for the ticket
event_timestamp	The timestamp of when the message was sent
data	The action-specific data for the event
id	The unique id for the ticket
type	The type of ticket (i.e. "Service Task", "Phishing", "Alert")
escalated	A flag to determine if the ticket has been marked as escalated
priority	The priority of the issue represented as an integer (1-3)
status	The status of the ticket in Cyderes's internal system
created_at	The timestamp of when the ticket was created
updated_at	The timestamp of when the ticket was updated
analyst_notes	The analyst's notes regarding the ticket
recommendations	The analyst's recommended actions regarding the ticket
short_description	A short description of the ticket
description	An explanation of the ticket
soar_references	References to Cyderes's SOAR
insights	The Cyderes insights for this issue
raw_event_description	The Cyderes raw case alert payload

Example Update Event Payload¶

{
    "action": "update",
    "ticket_id": "CYDERES-XXXXXX",
    "event_timestamp": "1677614794",
    "data": {
        "ticket": {
            "id": "CYDERES-XXXXXX",
            "type": "Alert",
            "short_description": "PUBLIC_IP_ADDRESS Example",
            "description": "",
            "escalated": true,
            "priority": 3,
            "status": "In-Progress",
            "created_at": "2022-12-31T00:00:00Z",
            "updated_at": "2022-12-31T12:00:00Z",
            "analyst_notes": "This is where an analyst can leave their notes.",
            "recommendations": "This is where an analyst can leave their recommendations",
            "soar_references": {
                "case_id": "XXXXXXX",
                "alert_id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
            },
            "insights": {
                "html_format": "",
                "json_format": ""
            },
            "raw_event_description": "[{}]"
        }
    }
}

Configuration Options¶

The following options are available for Webhooks:

Option	Default	Description
Escalated Only	True	Only send webhooks for escalated tickets
Send Service Requests	True	Specifies if messages are sent for "Service Request" tickets

Webhook Deployment Request¶

In order to request a webhook, please provide your CSM with the following information:

Configuration	Description
Endpoint URL	URL of the endpoint to send webhook payloads to
Endpoint Auth Type	The auth type for the endpoint (Basic, Bearer, or API Key)
Endpoint Auth	The username/password, bearer token, or API Key that the webhooks should use to authenticate with the endpoint
Configuration Options	Any changes to the default configuration options.