If you are looking for help setting up a webhook for a specific tool (such as Slack, Microsoft Teams, or a SIEM), see the setup guides in our knowledge base. This page is the companion reference that describes every field in the data we send and lists all the values each field can contain.
What a webhook is
A webhook is an automated message Defense.com sends to a web address (a URL) that you choose, the moment something happens in your account. Instead of you logging in to check for new threats or ticket updates, we push the information to you as soon as the event occurs. You can then forward that information into your own systems, a chat channel, a ticketing tool, or anywhere else that can receive a web request. When an event you have subscribed to happens, we send a single `POST` request to your URL. The body of that request is a small block of JSON (a structured, machine-readable format) describing what happened. The rest of this guide explains exactly what is in that JSON.
How delivery works
We only send webhooks to addresses that begin with https://, so the data is always encrypted in transit. If your endpoint is protected by a username and password, you can enable basic authentication when you create the webhook and we will include those credentials with every request.
If your endpoint cannot be reached or returns an error, we automatically try again. We will retry up to five times, waiting a little longer before each attempt (roughly one minute before the first retry, two minutes before the second, and so on). If all attempts fail, your account administrators are notified so the problem can be looked into. Every delivery attempt, successful or not, is recorded in the webhook history in your account so you can see what was sent and what response we received.
The two kinds of webhook
Defense.com can send webhooks about two kinds of record: threats and support tickets. When you create a webhook you choose which of these you want to hear about, and for each one you choose which events should trigger a message. The two record types and their available events are described below.
Every payload, regardless of type, includes a record_type field telling you which kind of record it is about and a trigger_action field telling you what just happened. That lets a single endpoint receive different kinds of webhooks and route each one correctly.
Threat webhooks
A threat is a security issue identified in your environment, such as a vulnerability found by a scan, a phishing result, or a security event. You can subscribe to four different events for threats.
The create event fires when a new threat is first identified. The update event fires when an existing threat changes, for example when its details or status are amended, or when a note is added to it. The closed event fires when a threat is resolved and moved into any of its closed states. The reopen event fires when a threat that was previously closed is moved back to an open state.
Threat payload fields
Field | Meaning |
record_type | Always |
id | The unique identifier for this threat |
company_id | The unique identifier for your company account |
trigger_action | What happened: |
title | A short title describing the threat |
description | A fuller description of the threat |
risk | How serious the threat is. See the risk levels below |
state | Where the threat is in its lifecycle. See the threat states below |
type | What part of Defense.com identified the threat. See the threat sources below |
url | A direct link to view the threat in Defense.com |
created_at | When the threat was first created, as a date and time |
When a webhook is triggered by someone adding a note to a threat, three extra fields are included describing that note.
Field | Meaning |
note_created_at | When the note was added |
note_created_by | The name of the person who added the note |
note_message | The text of the note |
Threat risk levels
The risk field tells you how serious the threat is. It will always be one of the following five values, listed here from least to most serious.
Value | Meaning |
info | Informational. Worth knowing about but not itself a risk |
low | A minor issue with limited potential impact |
medium | A moderate issue that should be addressed |
high | A serious issue that should be addressed promptly |
critical | A severe issue that needs urgent attention |
Threat states
The state field tells you where the threat is in its lifecycle. The first two values below are open states, meaning the threat is still active. The remaining four are closed states, meaning the threat has been resolved in one way or another.
Value | Meaning |
detected | The threat has been identified but nobody has been assigned to deal with it yet |
assigned | The threat is being worked on and remediation is underway |
false_positive | Closed. On review this was found not to be a genuine threat |
remediated | Closed. The threat has been fixed or resolved |
risk_accepted | Closed. A decision was made to accept the risk rather than fix it |
compensating_control | Closed. The threat was addressed with an alternative safeguard rather than a direct fix |
Threat sources
The type field tells you which part of Defense.com identified the threat. The table below shows the value you will receive in the payload alongside a plain description of what it means.
Value | Source |
User | A custom threat created manually |
AppScanner::Site | The application scanner |
Questionnaires::Question | A cyber assessment |
PenTest::Report | A penetration test |
Phishing::Campaign | A phishing campaign |
Recon::Report | Reconnaissance (recon) |
SIEM::SecurityEvent | A security event from the SIEM |
Intel::Item | Threat intelligence |
Scanner::Site | The vulnerability scanner |
EndpointProtection::CompanyPackage | Endpoint protection |
OrbitalAgent::Company | The Orbital agent |
Integrations::Microsoft365 | Microsoft Secure Score |
Training::Campaign | Security awareness training (training not completed) |
Company | A company-wide threat (e.g. no training campaign set up) |
Example threat payload
The example below shows a typical threat webhook for a newly created threat.
{
"record_type": "Threat",
"id": "0f9c8b7a-1234-5678-9abc-def012345678",
"company_id": "abc12345-6789-0def-1234-56789abcdef0",
"trigger_action": "create",
"title": "Outdated software detected on a public facing server",
"description": "A version of the web server software with known vulnerabilities was found.",
"risk": "high",
"state": "detected",
"type": "Scanner::Site",
"url": "https://my.defense.com/threats/0f9c8b7a-1234-5678-9abc-def012345678",
"created_at": "2026-06-19T09:30:00Z"
}
Support ticket webhooks
A support ticket is a request or conversation between you and the Defense.com support team. You can subscribe to three events for tickets.
The create event fires when a ticket is first opened. The update event fires when a ticket changes or a new reply is added. The closed event fires when a ticket is closed.
Support ticket payload fields
Field | Meaning |
record_type | Always |
id | The unique identifier for this ticket |
company_id | The unique identifier for your company account |
trigger_action | What happened: |
reference | The ticket reference code you can quote to support |
subject | The subject line of the ticket |
priority | How urgent the ticket is. See the priorities below |
state | Where the ticket is in its lifecycle. See the ticket states below |
url | A direct link to view the ticket in Defense.com |
created_at | When the ticket was opened, as a date and time |
As with threats, when a webhook is triggered by a new reply on the ticket, three extra fields describing that note are included: note_created_at, note_created_by, and note_message, with the same meanings as in the threat section above.
Support ticket priorities
The priority field tells you how urgent the ticket is.
Value | Meaning |
Critical | The most urgent level, for severe issues needing immediate attention |
Urgent | A pressing issue that needs a fast response |
Standard | A normal priority request |
Information Request | A request for information rather than an incident |
Service Request | A request for a specific service or action |
Support ticket states
The state field tells you where the ticket is in its lifecycle.
Value | Meaning |
new | The ticket has just been opened and is awaiting attention |
awaiting_reply | The ticket is with the support team, awaiting their reply |
awaiting_reply_on_hold | The ticket is with the support team but currently on hold |
awaiting_customer_reply | The support team is waiting for a reply from you |
awaiting_customer_approval | The support team is waiting for you to approve something |
closed | The ticket has been closed |
Example support ticket payload
The example below shows a support ticket webhook triggered by a new reply, which is why it includes the note fields.
{
"record_type": "Support Ticket",
"id": "11223344-5566-7788-99aa-bbccddeeff00",
"company_id": "abc12345-6789-0def-1234-56789abcdef0",
"trigger_action": "update",
"reference": "TES-TIN-GDATA",
"subject": "Question about my latest scan results",
"priority": "Standard",
"state": "awaiting_customer_reply",
"url": "https://my.defense.com/support/tickets/11223344-5566-7788-99aa-bbccddeeff00",
"created_at": "2026-06-19T08:15:00Z",
"note_created_at": "2026-06-19T10:42:00Z",
"note_created_by": "Alex Morgan",
"note_message": "Thanks, that answers my question."
}
Tips for handling webhooks reliably
Treat the record_type and trigger_action fields as your starting point, since together they tell you what the message is about and what happened. Where a field has a fixed set of possible values, such as risk, state, or priority, write your integration so that an unexpected new value is handled gracefully rather than causing an error, as we may add new values over time. Finally, remember that the same threat or ticket can generate several webhooks over its lifetime as its state changes, so use the id field to recognise when different messages refer to the same record.