Webhook¶
Webhooks are automated messages that send data to clients when tickets are created or modified. The data sent is different depending on the type of action that occurred.
These automated messages allow clients to receive ticket updates in real-time and handle the updates in their own systems without needing to poll the Cyderes TSI API.
If the ability to send over webhooks is needed, please reach out to your Customer Success Manager (CSM).
Event Actions¶
There are four actions that trigger a webhook:
| Action | Trigger |
|---|---|
| Comment | A comment is added or updated |
| Attachment | An attachment is added |
| Update | A ticket is updated or a ticket is created and the "Escalated Only option is disabled |
| Escalate | A ticket is escalated and the "Escalated Only" option is enabled |
The data provided from the webhook differs for each action.
Payloads¶
The following fields are provided in the response for every webhook
| 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 |
The contents of the data field differs for each action as described below.
Comment¶
| Field | Description |
|---|---|
| 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 |
{
"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¶
| Field | Description |
|---|---|
| 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 |
{
"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
Update¶
| Field | Description |
|---|---|
| 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 |
{
"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": "[{}]"
}
}
}
Escalate¶
The escalate action contains the same fields as the update action with the addition of a list of comments and attachments. The comments and attachment lists contain comments and attachments that were added to the ticket prior to escalation.
{
"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",
}
]
}
}
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 |
Configuration¶
The following information must be provided to the System Integrations development team to setup Webhooks for a client:
| Configuration | Description |
|---|---|
| Endpoint URL | The URL the client wants us to send the webhook messages to |
| Endpoint Auth Type | The auth type for the endpoint (basic or bearer) |
| Endpoint Auth | The username/password or bearer token that the webhooks should use to authenticate with the endpoint |
| Options | The options that the client wants set to non-default values. Please see the above. |