Webhook Event Reference

ContraForce delivers events to your endpoint over HTTPS as signed JSON. This page lists every event type the platform can send, the exact body shape for each, and the delivery rules that apply to all of them. Webhooks are managed under Settings → Developer Integrations in the portal, or through the /webhooks endpoints with the webhooks:read and webhooks:manage scopes. The portal shows the same sample deliveries as this page: use the info button next to an event when creating or editing a webhook to view and copy its sample payload.

Event Types

Event type	Display name	Routing	Fires when
`webhook.test.v1`	Webhook Test	Manual	You use Send test on a webhook to verify connectivity.
`incident.created.v1`	Incident Created	Subscription	A new incident is ingested into a monitored workspace. Also used by the manual Trigger webhook action on an incident.
`incident.closed.v1`	Incident Closed	Subscription	An incident reaches Closed, including closures performed in the vendor’s own portal. A close also fires `incident.status.changed.v1`.
`incident.status.changed.v1`	Incident Status Changed	Subscription	An incident moves to any status, including pauses, reopens and closes. Carries the previous and new status and the current owner.
`incident.assignee.changed.v1`	Incident Assignee Changed	Subscription	An incident is assigned, reassigned or unassigned, by an analyst, a bulk update, or the AI agent.
`incident.comment.added.v1`	Incident Comment Added	Subscription	An analyst, the AI agent, or a Gamebook adds a comment to an incident. Carries the full comment.
`gamebook.run.v1`	Gamebook Run	Subscription	A Gamebook is dispatched against an incident, by an analyst or by the AI agent.
`agent.investigation.completed.v1`	Agent Investigation Completed	Externally configured	A Security Delivery Agent finishes an investigation and reaches a verdict whose classification card points at a webhook.

Routing models

Subscription routing

The webhook lists the event type in its eventTypes array. Every active webhook in scope receives the event.Scope resolution covers the incident’s own account plus any managing service provider accounts. A service provider webhook with a non-empty monitoredAccountIds list only receives events from the accounts it lists; an empty list means all managed accounts.

Externally configured routing

Subscribing alone does not opt a webhook in. An owning entity has to name the webhook explicitly. Today this applies only to agent.investigation.completed.v1, where an Agent Configuration’s classification card selects the target webhook.The webhook must also keep agent.investigation.completed.v1 in its eventTypes. If it is unsubscribed while still bound to a classification card, the delivery is recorded as Failed in the delivery log rather than dropped silently.

Manual routing

webhook.test.v1 is only produced by the Send test action against one specific webhook. It is not a subscribable event.The incident Trigger webhook action is also manual, but it reuses incident.created.v1 so that existing receivers process it without code changes. Subscription matching is bypassed for that fire, though monitoredAccountIds is still enforced.

The Delivery Envelope

Every event, regardless of type, is delivered as the same outer envelope. The event-specific schema lives under data.

{
  "type": "incident.created.v1",
  "timestamp": "2026-08-03T14:22:07.881Z",
  "isTest": false,
  "occurredAt": "2026-08-03T14:21:55.000Z",
  "data": { }
}

Field	Type	Description
`type`	string	The event type. Matches the `X-CF-Schema` header.
`timestamp`	string	ISO 8601 time the delivery attempt was built.
`isTest`	boolean	`true` for test deliveries only.
`occurredAt`	string	ISO 8601 time the underlying event happened, which can be earlier than `timestamp`.
`data`	object	The event payload. Shape depends on `type`.

Verify the signature over the full raw body, envelope included. Do not sign or hash only the data object.

All payload property names are camelCase.

Request Headers

Header	Value	Notes
`Content-Type`	`application/json`	Body is UTF-8 encoded JSON.
`X-CF-Schema`	The event type	Branch on this. Default-ignore types you do not recognize.
`X-CF-Event-Id`	GUID	Stable per logical event. Use it to deduplicate.
`X-CF-Timestamp`	ISO 8601 timestamp	Reject if more than 5 minutes from your clock.
`X-CF-Signature`	Base64 HMAC-SHA256	See below.
`X-CF-Test`	`true` or `false`	`true` only for test deliveries.
`Authorization`	`Bearer <token>` or `Basic <base64>`	Present only if you configured authentication on the webhook.

Verifying the Signature

The signature covers the timestamp and the exact raw request body:

signature = Base64( HMAC_SHA256( signing_key, X-CF-Timestamp + "." + raw_body ) )

The signing_key is the secret shown once when the webhook was created, unless you supplied your own signing token override when setting bearer-token credentials, in which case it is that token.

import base64, hashlib, hmac, time
from datetime import datetime, timezone

def verify(signing_key: str, headers: dict, raw_body: bytes) -> bool:
    ts = headers["X-CF-Timestamp"]
    sent = headers["X-CF-Signature"]
    signed = ts.encode() + b"." + raw_body
    expected = base64.b64encode(
        hmac.new(signing_key.encode(), signed, hashlib.sha256).digest()
    ).decode()
    if not hmac.compare_digest(expected, sent):
        return False
    age = abs(time.time() - datetime.fromisoformat(ts).replace(tzinfo=timezone.utc).timestamp())
    return age <= 300

static bool Verify(string signingKey, string timestamp, string sentSignature, byte[] rawBody)
{
    var signed = System.Text.Encoding.UTF8.GetBytes(timestamp + ".")
        .Concat(rawBody).ToArray();
    using var hmac = new System.Security.Cryptography.HMACSHA256(
        System.Text.Encoding.UTF8.GetBytes(signingKey));
    var expected = Convert.ToBase64String(hmac.ComputeHash(signed));
    var match = System.Security.Cryptography.CryptographicOperations.FixedTimeEquals(
        System.Text.Encoding.UTF8.GetBytes(expected),
        System.Text.Encoding.UTF8.GetBytes(sentSignature));
    var age = Math.Abs((DateTimeOffset.UtcNow - DateTimeOffset.Parse(timestamp)).TotalSeconds);
    return match && age <= 300;
}

`webhook.test.v1`

A synthetic connectivity check, sent only by the Send test action on a single webhook. It carries X-CF-Test: true and isTest: true, and is signed exactly like a live event, so you can validate your verification code end to end before any real traffic arrives. The payload mirrors the incident.created.v1 shape with fixed sample values. Both vendor blocks are populated in the test event so you can build against the full shape; a real incident carries whichever blocks apply to it.

{
  "type": "webhook.test.v1",
  "timestamp": "2026-08-03T14:22:07.881Z",
  "isTest": true,
  "occurredAt": "2026-08-03T14:22:07.881Z",
  "data": {
    "accountId": "11111111-1111-1111-1111-111111111111",
    "accountName": "Contoso Production",
    "incidentId": "test-00000000-0000-0000-0000-000000000000",
    "incidentNumber": 0,
    "title": "Test Incident — Webhook Connectivity Verification",
    "description": "This is a test event generated by ContraForce to verify your webhook endpoint is configured correctly and receiving events.",
    "severity": "Informational",
    "source": "contraforce",
    "sourceDisplayName": "ContraForce",
    "createdAt": "2026-08-03T14:22:07.881Z",
    "lastActivityAt": "2026-08-03T14:22:07.881Z",
    "alertProductNames": ["ContraForce EventCast"],
    "vendorIdentifiers": {
      "sentinel": {
        "armId": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/test-resource-group/providers/Microsoft.OperationalInsights/workspaces/test-workspace/providers/Microsoft.SecurityInsights/incidents/00000000-0000-0000-0000-000000000000",
        "incidentId": "00000000-0000-0000-0000-000000000000",
        "subscriptionId": "00000000-0000-0000-0000-000000000000",
        "resourceGroupName": "test-resource-group",
        "workspaceName": "test-workspace",
        "incidentNumber": 0,
        "portalUrl": "https://portal.azure.com/#example-test-incident"
      },
      "defender": {
        "incidentId": "0",
        "tenantId": "00000000-0000-0000-0000-000000000000",
        "portalUrl": "https://security.microsoft.com/incidents/0"
      }
    },
    "alerts": [
      {
        "title": "Webhook Test Alert",
        "severity": "Informational",
        "productName": "ContraForce EventCast",
        "vendorName": "ContraForce"
      }
    ],
    "owner": {
      "displayName": "ContraForce Test User",
      "email": "test-user@example.com"
    },
    "entities": [
      { "type": "account", "displayName": "test-account@example.com" },
      { "type": "host", "displayName": "DESKTOP-TEST001" },
      { "type": "ip", "displayName": "192.0.2.1" }
    ]
  }
}

Test deliveries are excluded from the auto-disable circuit breaker, so a failing test never takes a live webhook offline.

`incident.created.v1`

Fires when a new incident is ingested into a workspace the webhook monitors. The same event type is emitted by the incident Trigger webhook action so that receivers do not need a separate code path for a manually replayed incident.

{
  "type": "incident.created.v1",
  "timestamp": "2026-08-03T14:22:07.881Z",
  "isTest": false,
  "occurredAt": "2026-08-03T14:21:55.000Z",
  "data": {
    "accountId": "11111111-1111-1111-1111-111111111111",
    "accountName": "Contoso Production",
    "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
    "incidentNumber": 4242,
    "title": "Suspicious sign-in from impossible travel",
    "description": "Multiple sign-ins from geographically distant locations within a short window.",
    "severity": "High",
    "source": "sentinel",
    "sourceDisplayName": "Microsoft Sentinel",
    "owner": {
      "displayName": "Jane Doe",
      "email": "jdoe@contoso.example"
    },
    "createdAt": "2026-08-03T14:21:55.000Z",
    "lastActivityAt": "2026-08-03T14:21:58.000Z",
    "occurredAt": "2026-08-03T14:21:55.000Z",
    "alertProductNames": ["Microsoft Entra ID Protection"],
    "vendorIdentifiers": {
      "sentinel": {
        "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "subscriptionId": "22222222-2222-2222-2222-222222222222",
        "resourceGroupName": "rg-security",
        "workspaceName": "law-contoso",
        "incidentNumber": 4242,
        "portalUrl": "https://portal.azure.com/#blade/Microsoft_Azure_Security_Insights/IncidentBlade"
      },
      "defender": {
        "incidentId": "9915",
        "tenantId": "33333333-3333-3333-3333-333333333333",
        "portalUrl": "https://security.microsoft.com/incidents/9915"
      }
    },
    "alerts": [
      {
        "title": "Impossible travel activity",
        "severity": "High",
        "productName": "Microsoft Entra ID Protection",
        "vendorName": "Microsoft"
      }
    ],
    "entities": [
      { "type": "Account", "displayName": "jdoe@contoso.example" },
      { "type": "IP", "displayName": "198.51.100.24" }
    ]
  }
}

Fields

Field	Type	Description
`accountId` / `accountName`	string	The workspace the incident belongs to.
`incidentId`	string	The source system’s incident identifier.
`incidentNumber`	number \| null	The incident number shown in the portal.
`title`	string	Incident title.
`description`	string	Incident description, empty string when the source provides none.
`severity`	string	`Informational`, `Low`, `Medium`, `High`, or `Critical`.
`source`	string	Detection source, lowercased for this event, for example `sentinel`, `defenderxdr`, `crowdstrike`.
`sourceDisplayName`	string	Human-readable source name.
`owner`	object \| null	Assigned owner at creation, omitted when unassigned. The same person is called `assignee` on every later incident event; this name predates them and is kept for compatibility.
`createdAt`	string	ISO 8601 creation time.
`lastActivityAt`	string \| null	ISO 8601 time of the most recent activity.
`occurredAt`	string	Duplicate of `createdAt`, retained for receivers that read it from `data`.
`alertProductNames`	string[]	Distinct product names across the incident’s alerts.
`vendorIdentifiers`	object	Vendor identifiers for this incident. See Vendor identifiers. Absent when none could be resolved.
`alerts[]`	array	Each with `title`, `severity`, `productName`, `vendorName`.
`entities[]`	array	Each with `type` and `displayName`. `Ip` and `Url` are normalized to `IP` and `URL`.

Null fields are omitted from this payload rather than serialized as null. Treat a missing owner or lastActivityAt as absent.

Vendor identifiers

incident.created.v1 carries an vendorIdentifiers object holding the identifiers of every vendor system known to hold a record of the incident. It exists because incidentId alone is not always enough to act: addressing a Microsoft Sentinel incident over ARM needs the full resource id, and one real-world incident can exist in both Defender XDR and Sentinel under different ids. The same object rides on incident.created.v1, incident.closed.v1, incident.status.changed.v1, incident.assignee.changed.v1 and incident.comment.added.v1, and is exposed on the incident representation in the REST API, so a receiver resolves an incident the same way whichever surface it came from.

"vendorIdentifiers": {
  "sentinel": {
    "armId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}/providers/Microsoft.OperationalInsights/workspaces/{workspaceName}/providers/Microsoft.SecurityInsights/incidents/{incidentId}",
    "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
    "subscriptionId": "22222222-2222-2222-2222-222222222222",
    "resourceGroupName": "rg-security",
    "workspaceName": "law-contoso",
    "incidentNumber": 4242,
    "portalUrl": "https://portal.azure.com/..."
  },
  "defender": {
    "incidentId": "9915",
    "tenantId": "33333333-3333-3333-3333-333333333333",
    "portalUrl": "https://security.microsoft.com/incidents/9915"
  }
}

Field	Type	Description
`sentinel.armId`	string	Full ARM resource id. This is what Azure automation, Logic Apps, and the Sentinel REST API address the incident by.
`sentinel.incidentId`	string	The Sentinel incident GUID, the last segment of `armId`.
`sentinel.subscriptionId`	string	Subscription holding the Log Analytics workspace.
`sentinel.resourceGroupName`	string	Resource group holding the Log Analytics workspace.
`sentinel.workspaceName`	string	Log Analytics workspace name. Not the ContraForce workspace name.
`sentinel.incidentNumber`	number	Incident number within the Sentinel workspace.
`sentinel.portalUrl`	string	Link to the incident in the Microsoft Sentinel portal.
`defender.incidentId`	string	The Defender XDR incident id.
`defender.tenantId`	string	Entra tenant the Defender incident belongs to.
`defender.portalUrl`	string	Link to the incident in the Microsoft Defender portal.

Which blocks are present

Every block and every field inside it is conditional. Treat an absent block as “not resolvable for this incident”, not as an error.

Incident source	`sentinel`	`defender`
Sentinel, generated by a Sentinel analytics rule	Yes	No. The incident exists only in Sentinel.
Sentinel, forwarded in from Defender XDR	Yes	Yes, read from Sentinel’s own `providerIncidentId`.
Defender XDR, workspace also running Sentinel	Usually, once the Sentinel counterpart exists	Yes
Defender XDR, workspace with no Sentinel module	No	Yes
CrowdStrike, SentinelOne, and other sources	No	No. The `vendorIdentifiers` object is omitted entirely.

For a Defender XDR incident, the sentinel block depends on Microsoft having already created the Sentinel counterpart. Immediately after an incident is created that copy may not exist yet, so the block can be absent on incident.created.v1 and present when the same incident is later read over the REST API. Branch on the field you need being present rather than assuming it always will be.

This object is additive. Existing fields, including the top-level incidentId, are unchanged and continue to carry the identifier of the source the incident was ingested from.

`incident.closed.v1`

Fires when an incident reaches Closed, whichever route got it there: the portal, a bulk close, the AI agent, or the public API. Closures performed directly in the vendor’s own console are also picked up by reconciliation and delivered here, distinguished by closedBy.origin.

A close also fires incident.status.changed.v1 for webhooks subscribed to it. The two are separate deliveries with different event IDs. Handle closes from one of them: this event when you need the verdict and closing comment, the status event when you mirror every status.

{
  "type": "incident.closed.v1",
  "timestamp": "2026-08-03T16:04:12.117Z",
  "isTest": false,
  "occurredAt": "2026-08-03T16:04:12.117Z",
  "data": {
    "accountId": "11111111-1111-1111-1111-111111111111",
    "accountName": "Contoso Production",
    "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
    "incidentNumber": 4242,
    "title": "Suspicious sign-in from impossible travel",
    "severity": "High",
    "source": "Sentinel",
    "sourceDisplayName": "Microsoft Sentinel",
    "classification": "TruePositive",
    "classificationReason": "SuspiciousActivity",
    "comment": "Confirmed credential theft. User reset and sessions revoked.",
    "assignee": {
      "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "displayName": "Jane Doe",
      "email": "jdoe@contoso.example",
      "isAgent": null
    },
    "vendorIdentifiers": {
      "sentinel": {
        "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "subscriptionId": "22222222-2222-2222-2222-222222222222",
        "resourceGroupName": "rg-security",
        "workspaceName": "law-contoso",
        "incidentNumber": 4242,
        "portalUrl": "https://portal.azure.com/..."
      }
    },
    "closedAt": "2026-08-03T16:04:12.117Z",
    "closedBy": {
      "displayName": "Jane Doe",
      "origin": "analyst"
    }
  }
}

Fields

Field	Type	Description
`accountId` / `accountName`	string	The workspace the incident belongs to.
`incidentId`	string	The source system’s incident identifier.
`incidentNumber`	number \| null	The incident number shown in the portal.
`title`	string	Incident title.
`severity`	string	Incident severity at close.
`source`	string	Detection source in PascalCase for this event, for example `Sentinel`.
`sourceDisplayName`	string	Human-readable source name.
`classification`	string \| null	Canonical ContraForce classification: `TruePositive`, `FalsePositive`, `BenignPositive`, or `Undetermined`.
`classificationReason`	string \| null	Canonical reason name, when one was recorded.
`comment`	string \| null	Free-text closing comment, when one was provided.
`assignee`	object \| null	Who was working the incident when it closed, with `id`, `displayName`, `email` and `isAgent`. `null` when unassigned. `isAgent` is always `null` here: the owner comes from the vendor record, which does not say whether it is an agent. Distinct from `closedBy`, which is who performed the close.
`vendorIdentifiers`	object \| null	Vendor identifiers for this incident. See Vendor identifiers. Unlike `incident.created.v1`, this event serializes nulls, so the key is present and `null` when nothing resolved.
`closedAt`	string	ISO 8601 close time.
`closedBy.displayName`	string	Closing analyst, or the upstream source label for vendor-portal closures.
`closedBy.origin`	string	`analyst` for closures through ContraForce, `upstream` for closures detected in the vendor’s portal.

Branch on classification, not on vendor strings. ContraForce normalizes every source’s closure vocabulary into the four canonical values, so your integration does not have to track vendor enum changes. See Incident classification.

`incident.status.changed.v1`

Fires on every status transition an incident goes through in ContraForce: the portal, a bulk update, the AI agent, or the public API. Closures picked up from the vendor’s own console by reconciliation are delivered too, with changedBy.origin set to upstream.

This event fires on close as well. A close produces both this event (with status: "Closed") and incident.closed.v1, as two separate deliveries with different event IDs. Subscribe to this event to mirror every status into another system, and to incident.closed.v1 when you only care about the verdict and the closing comment. Subscribing to both means handling each close twice.

{
  "type": "incident.status.changed.v1",
  "timestamp": "2026-08-03T15:40:21.004Z",
  "isTest": false,
  "occurredAt": "2026-08-03T15:40:21.004Z",
  "data": {
    "accountId": "11111111-1111-1111-1111-111111111111",
    "accountName": "Contoso Production",
    "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
    "incidentNumber": 4242,
    "title": "Suspicious sign-in from impossible travel",
    "severity": "High",
    "source": "Sentinel",
    "sourceDisplayName": "Microsoft Sentinel",
    "previousStatus": "Active",
    "status": "WaitingOnCustomer",
    "classification": null,
    "classificationReason": null,
    "assignee": {
      "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "displayName": "Jane Doe",
      "email": "jdoe@contoso.example",
      "isAgent": null
    },
    "vendorIdentifiers": {
      "sentinel": {
        "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "subscriptionId": "22222222-2222-2222-2222-222222222222",
        "resourceGroupName": "rg-security",
        "workspaceName": "law-contoso",
        "incidentNumber": 4242,
        "portalUrl": "https://portal.azure.com/..."
      }
    },
    "changedAt": "2026-08-03T15:40:21.004Z",
    "changedBy": {
      "displayName": "Jane Doe",
      "origin": "analyst"
    }
  }
}

Fields

Field	Type	Description
`accountId` / `accountName`	string	The workspace the incident belongs to.
`incidentId`	string	The source system’s incident identifier.
`incidentNumber`	number \| null	The incident number shown in the portal.
`title`	string	Incident title.
`severity`	string	Incident severity at the time of the change.
`source`	string	Detection source in PascalCase for this event, for example `Sentinel`.
`sourceDisplayName`	string	Human-readable source name.
`previousStatus`	string \| null	Status before the transition. `null` for closures detected in the vendor’s console, where ContraForce does not know the prior status.
`status`	string	Status after the transition: `New`, `Active`, `Closed`, `OnHold`, or `WaitingOnCustomer`.
`classification`	string \| null	Canonical ContraForce classification, present only when `status` is `Closed`.
`classificationReason`	string \| null	Canonical reason name, present only on a close that recorded one.
`assignee`	object \| null	The incident’s owner when the change happened, with `id`, `displayName`, `email` and `isAgent`. `null` when unassigned. `isAgent` is always `null` here: the owner comes from the vendor record, which does not say whether it is an agent.
`vendorIdentifiers`	object \| null	Vendor identifiers for this incident. See Vendor identifiers. The key is present and `null` when nothing resolved.
`changedAt`	string	ISO 8601 time of the change. For upstream closures, the vendor’s own modification time.
`changedBy.displayName`	string	The acting analyst or agent, or the upstream source label for vendor-console changes.
`changedBy.origin`	string	`analyst` for changes through ContraForce, `upstream` for changes detected in the vendor’s portal.

OnHold and WaitingOnCustomer are ContraForce statuses. They pause the SLA clocks and never propagate to the vendor, so a receiver mirroring status into a PSA should map them to its own waiting states rather than expect to find them in Sentinel or Defender.

`incident.assignee.changed.v1`

Fires when an incident is assigned, reassigned or unassigned through ContraForce, whether by an analyst, a bulk update, or a Security Delivery Agent assigning itself. Ownership changes made directly in the vendor’s console are not detected.

{
  "type": "incident.assignee.changed.v1",
  "timestamp": "2026-08-03T14:25:03.512Z",
  "isTest": false,
  "occurredAt": "2026-08-03T14:25:03.512Z",
  "data": {
    "accountId": "11111111-1111-1111-1111-111111111111",
    "accountName": "Contoso Production",
    "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
    "incidentNumber": 4242,
    "title": "Suspicious sign-in from impossible travel",
    "severity": "High",
    "source": "Sentinel",
    "sourceDisplayName": "Microsoft Sentinel",
    "previousAssignee": null,
    "assignee": {
      "id": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f",
      "displayName": "Jane Doe",
      "email": "jdoe@contoso.example",
      "isAgent": false
    },
    "vendorIdentifiers": {
      "sentinel": {
        "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "subscriptionId": "22222222-2222-2222-2222-222222222222",
        "resourceGroupName": "rg-security",
        "workspaceName": "law-contoso",
        "incidentNumber": 4242,
        "portalUrl": "https://portal.azure.com/..."
      }
    },
    "changedAt": "2026-08-03T14:25:03.512Z",
    "changedBy": {
      "displayName": "Jane Doe",
      "origin": "analyst"
    }
  }
}

Fields

Field	Type	Description
`accountId` / `accountName`	string	The workspace the incident belongs to.
`incidentId`	string	The source system’s incident identifier.
`incidentNumber`	number \| null	The incident number shown in the portal.
`title`	string	Incident title.
`severity`	string	Incident severity at the time of the change.
`source`	string	Detection source in PascalCase for this event, for example `Sentinel`.
`sourceDisplayName`	string	Human-readable source name.
`previousAssignee`	object \| null	The owner before the change. `null` when the incident was unassigned.
`assignee`	object \| null	The owner after the change. `null` when the incident was unassigned.
`*.id`	string	ContraForce user or agent id. Can be empty on `previousAssignee` when the vendor record carries only a name or email.
`*.displayName`	string	Owner display name.
`*.email`	string \| null	Owner email, when known.
`*.isAgent`	boolean \| null	`true` for a Security Delivery Agent, `false` for a portal user. `null` on `previousAssignee`, which comes from the vendor record and does not say which it was.
`vendorIdentifiers`	object \| null	Vendor identifiers for this incident. See Vendor identifiers. The key is present and `null` when nothing resolved.
`changedAt`	string	ISO 8601 time of the change.
`changedBy.displayName`	string	The analyst or agent that made the change.
`changedBy.origin`	string	Always `analyst` today; reserved for changes detected in the vendor’s portal.

A previousAssignee of null with an assignee is a first assignment, and an assignee of null is an unassignment. Use assignee.isAgent to skip the agent’s own self-assignment when your ticketing sync should only follow human owners.

`incident.comment.added.v1`

Fires when a comment is added to an incident through ContraForce by an analyst, a Security Delivery Agent, or a Gamebook. Comments written directly in the vendor’s console are not detected, and the closing comment entered on a close travels on incident.closed.v1 rather than here.

{
  "type": "incident.comment.added.v1",
  "timestamp": "2026-08-03T14:31:40.220Z",
  "isTest": false,
  "occurredAt": "2026-08-03T14:31:39.870Z",
  "data": {
    "accountId": "11111111-1111-1111-1111-111111111111",
    "accountName": "Contoso Production",
    "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
    "incidentNumber": 4242,
    "title": "Suspicious sign-in from impossible travel",
    "severity": "High",
    "source": "Sentinel",
    "sourceDisplayName": "Microsoft Sentinel",
    "vendorIdentifiers": {
      "sentinel": {
        "armId": "/subscriptions/22222222-2222-2222-2222-222222222222/resourceGroups/rg-security/providers/Microsoft.OperationalInsights/workspaces/law-contoso/providers/Microsoft.SecurityInsights/incidents/a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
        "subscriptionId": "22222222-2222-2222-2222-222222222222",
        "resourceGroupName": "rg-security",
        "workspaceName": "law-contoso",
        "incidentNumber": 4242,
        "portalUrl": "https://portal.azure.com/..."
      }
    },
    "comment": {
      "id": "3d2f7b1c-9e8a-4f65-b0c4-1a2b3c4d5e6f",
      "content": "Confirmed with the user; the sign-in was not theirs. Resetting the password and revoking sessions.",
      "createdAt": "2026-08-03T14:31:39.870Z",
      "author": {
        "displayName": "Jane Doe",
        "email": "jdoe@contoso.example",
        "type": "analyst",
        "agentName": null
      },
      "ticketId": "T0012345",
      "ticketNoteId": "N-77"
    }
  }
}

Fields

Field	Type	Description
`accountId` / `accountName`	string	The workspace the incident belongs to.
`incidentId`	string	The source system’s incident identifier.
`incidentNumber`	number \| null	The incident number shown in the portal.
`title`	string \| null	Incident title.
`severity`	string \| null	Incident severity when the comment was added.
`source`	string	Detection source in PascalCase for this event, for example `Sentinel`.
`sourceDisplayName`	string \| null	Human-readable source name.
`vendorIdentifiers`	object \| null	Vendor identifiers for this incident. See Vendor identifiers.
`comment.id`	string	The comment id in the source system, or a ContraForce id for sources that do not expose a stable comment id.
`comment.content`	string	The full comment text as submitted.
`comment.createdAt`	string	ISO 8601 time the comment was created.
`comment.author.displayName`	string	Who wrote the comment.
`comment.author.email`	string \| null	Author email, when the author is a portal or API user.
`comment.author.type`	string	`analyst` for a portal or API user, `agent` for a Security Delivery Agent.
`comment.author.agentName`	string \| null	The agent’s name when `type` is `agent`.
`comment.ticketId`	string \| null	The PSA ticket the comment was mirrored to as a note, when the workspace has a ticketing integration.
`comment.ticketNoteId`	string \| null	The note created on `ticketId`, when one was. Use it to avoid posting the same note a second time.

The incident block (incidentNumber, title, severity, sourceDisplayName, vendorIdentifiers) is read from the source system when the event is built. If that read fails, the event is still delivered with those fields null. incidentId, source and comment are always present, so key your handler on those.

`gamebook.run.v1`

Fires when a Gamebook is dispatched to the executor against an incident, whether an analyst started it from the portal or public API, or the AI agent did.

Gamebooks awaiting approval do not fire this event while queued. The event is emitted when the run is actually dispatched.

{
  "type": "gamebook.run.v1",
  "timestamp": "2026-08-03T15:10:44.502Z",
  "isTest": false,
  "occurredAt": "2026-08-03T15:10:44.502Z",
  "data": {
    "accountId": "11111111-1111-1111-1111-111111111111",
    "accountName": "Contoso Production",
    "incidentId": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
    "incidentNumber": 4242,
    "title": "Compromised account containment",
    "source": "Sentinel",
    "gamebookId": "3c9d1b7e-2f44-4a86-8c11-9e0f7d5a2b31",
    "gamebookTitle": "Compromised account containment",
    "playbooks": ["Disable user", "Revoke sign-in sessions"],
    "runAt": "2026-08-03T15:10:44.502Z",
    "runBy": {
      "displayName": "Jane Doe"
    }
  }
}

Fields

Field	Type	Description
`accountId` / `accountName`	string	The workspace the incident belongs to.
`incidentId`	string	The source system’s incident identifier.
`incidentNumber`	number \| null	The incident number shown in the portal.
`title`	string	The gamebook title. Duplicates `gamebookTitle`; it is not the incident title.
`source`	string	Detection source of the incident in PascalCase, for example `Sentinel`.
`gamebookId`	string	GUID of the gamebook that ran.
`gamebookTitle`	string	Display title of the gamebook.
`playbooks`	string[]	Display names of the playbooks in the dispatched gameplan.
`runAt`	string	ISO 8601 dispatch time.
`runBy.displayName`	string	The triggering identity: an analyst’s name, or the AI agent’s service identity.

`agent.investigation.completed.v1`

Fires once per investigation, when a Security Delivery Agent completes and reaches a classification whose card has a webhook custom action configured.

This event is configured per classification on an Agent Configuration card, not as a broadcast subscription. Set it up under Configuring Security Delivery Agents by enabling Advanced mode and choosing a webhook as the custom action for a classification. Full walkthrough and troubleshooting: Agent Investigation Completed Webhook.

{
  "type": "agent.investigation.completed.v1",
  "timestamp": "2026-08-03T14:31:09.740Z",
  "isTest": false,
  "occurredAt": "2026-08-03T14:31:02.310Z",
  "data": {
    "workspace": {
      "id": "11111111-1111-1111-1111-111111111111",
      "alias": "contoso",
      "name": "Contoso Production"
    },
    "agent": {
      "id": "5b2e9c4a-77d1-4c0b-a8f3-2d6e1c9b0a55",
      "name": "Tier 1 Triage Agent"
    },
    "incident": {
      "id": "a7f3c1e2-0000-4b1a-9c3d-5f6e7a8b9c0d",
      "number": 4242,
      "source": "Sentinel",
      "title": "Suspicious sign-in from impossible travel",
      "severity": "High",
      "status": "Active"
    },
    "verdict": {
      "classificationBucket": "TruePositive",
      "classificationReason": "SuspiciousActivity",
      "classificationReasonComment": "Confirmed credential theft",
      "comment": "Sign-in originated from a known-malicious ASN minutes after a login from the user's usual location.",
      "maliciousScore": 87
    },
    "gamebookRecommendation": {
      "incidentNumber": 4242,
      "incidentTitle": "Suspicious sign-in from impossible travel",
      "playbooks": [
        {
          "playbookId": "disable-user",
          "affectedEntity": "Account",
          "entityId": "jdoe@contoso.example",
          "sequence": 1
        }
      ]
    }
  }
}

Fields

Field	Type	Description
`workspace.id` / `alias` / `name`	string	The ContraForce workspace the incident belongs to.
`agent.id` / `name`	string	The Security Delivery Agent that ran the investigation.
`incident.id`	string	The source system’s incident identifier.
`incident.number`	number	The incident number shown in the portal.
`incident.source`	string	Detection source in PascalCase, for example `Sentinel`.
`incident.title`	string	Incident title.
`incident.severity`	string	Incident severity.
`incident.status`	string	Incident status at completion.
`verdict.classificationBucket`	string	The agent’s verdict. One of `TruePositive`, `BenignPositive`, `FalsePositive`, `Undetermined`.
`verdict.classificationReason`	string \| null	Reason code for the classification.
`verdict.classificationReasonComment`	string \| null	Free-text reason detail.
`verdict.comment`	string	The agent’s investigation summary comment.
`verdict.maliciousScore`	number \| null	How malicious the agent judged the incident, 0-100. See Malicious score.
`gamebookRecommendation`	object \| null	Present only when the agent recommended gamebooks.
`gamebookRecommendation.playbooks[]`	array	Each with `playbookId`, `affectedEntity`, `entityId`, and `sequence`.

Malicious score

verdict.maliciousScore reports how malicious the agent judged the incident to be, on a 0-100 scale. It lets you branch on degree rather than only on the four-value classificationBucket, for example auto-closing below a threshold while escalating above one.

The score is a maliciousness reading, not a confidence reading. A verdict the agent is completely certain is a False Positive scores near 0, not near 100. Reading it as confidence inverts the meaning of every benign verdict.

Range	Meaning
0-34	Judged benign.
35-69	Ambiguous, worth a human look.
70-100	Judged malicious.

The bands above match how the portal colors the score. They are guidance for reading a value, not thresholds the platform enforces. maliciousScore is null when the investigation came through the legacy agent path, which does not collect a score. The key is always present on this payload, so check for null rather than for absence.

Delivery Rules

These apply to every event type.

Retries

Delivery is at-least-once. A failed attempt is retried with a fixed backoff, up to 10 attempts within a 5 minute window from the first attempt. Whichever limit is hit first ends the retry budget and the event is dead-lettered.

Next attempt	2	3	4	5	6	7	8	9	10
Backoff	5s	10s	15s	20s	30s	30s	40s	50s	60s

Retries are triggered by HTTP 408, 429, 500, 502, 503, and 504, and by connection or timeout errors. Any other non-success status is treated as a permanent failure and is not retried. A Retry-After header is honored when it is longer than the scheduled backoff, clamped to the 5 minute retry window.

Retries reuse the same X-CF-Event-Id. Make your handler idempotent and deduplicate on that value.

Event IDs

incident.created.v1, incident.closed.v1, gamebook.run.v1 and incident.comment.added.v1 derive a deterministic event ID from the underlying subject (the comment, for comment events), so a republished event produces the same ID and can be deduplicated. incident.status.changed.v1 and incident.assignee.changed.v1 get a fresh ID per transition. The same transition can happen more than once on one incident (pause, resume, pause again), and each occurrence is a distinct event that a subject-derived ID would wrongly collapse. Test events and manually triggered incident fires get a fresh ID per fire, which is what distinguishes a manual replay from the original automatic event.

Auto-disable

If 5 or more distinct incidents fail final delivery to the same webhook within a rolling 24 hours, the webhook is automatically disabled and stops receiving events. Test deliveries never count toward this threshold. Re-enable it with POST /webhooks/{id}/enable or from the webhook detail page in the portal, after fixing the endpoint.

Delivery logs

Every delivery attempt is recorded as a delivery-log entry on the webhook. Entries are listed under Settings → Developer Integrations in the portal and through GET /webhooks/{id}/delivery-logs. A delivery-log entry is delivery metadata, not a copy of the event. Incident content is processed in memory while the event is built and sent, and none of it is written to the log.

Retained	Not retained
Event ID, event type, and when the event occurred	The event body that was sent
Outcome (`Pending`, `Succeeded`, `Failed`), HTTP status code, latency, and the HTTP reason phrase on failure	The response body your endpoint returned
Attempt number and, for retries, the ID of the original delivery	The incident title
Source workspace ID and name
Incident ID, source, severity, status, and the label `Incident #<number>`

Entries are kept for a bounded period and expire automatically; they are not retained for the life of the account. Opening an entry in the portal, or calling GET /webhooks/{id}/delivery-logs/{logId}, shows the incident as it stands now, fetched live from the source system. It is not a snapshot of what was sent. When the incident no longer exists, the entry shows its delivery metadata and no body. See the delivery log model for the response shape.

Entries written before 2026-08-27 may still carry a stored body and response snippet until they expire or are purged.

Redelivery

A Failed entry can be sent again with POST /webhooks/{id}/delivery-logs/{logId}/redeliver?createdAt= or from the entry’s details in the portal. Because the body is not stored, redelivery rebuilds it from the source incident at the moment you redeliver.

The envelope keeps the original X-CF-Event-Id and occurredAt, so deduplication treats it as the same event.
data reflects the incident’s current state. Status, owner, severity, and alerts can differ from what the original attempt carried.
Only incident.created.v1 can be rebuilt. incident.closed.v1, gamebook.run.v1, and agent.investigation.completed.v1 cannot be redelivered.

When redelivery is not possible the response is a 422 with code VALIDATION_ERROR, or a 409 with code CONFLICT. The detail field says why:

Status	`detail`	What to do
`422`	Delivery is not in Failed status	Only `Failed` entries can be redelivered.
`409`	Redelivery already in progress	Wait for the in-flight redelivery to finish; the entry’s `redeliveryRequestedAt` is set.
`422`	This delivery cannot be rebuilt for redelivery	The event type has no rebuild path, or the entry predates payload rebuild.
`422`	The incident that produced this event is no longer available	The incident was deleted, or its workspace was offboarded or the detection module disconnected.
`422`	Webhook configuration status is `Paused` or `Disabled`	Resume or re-enable the webhook, then redeliver.

Requirements for your endpoint

Must be reachable over HTTPS. Plain HTTP, localhost, and private network addresses are rejected at configuration time.
Must respond within 30 seconds. Acknowledge with a 2xx immediately and do the real work asynchronously.
Response bodies are read up to 1 MB and then discarded. The delivery log records the HTTP status code and latency, never the body.
Should default-ignore unknown values of X-CF-Schema so new event types do not break your handler.

Subscribing

Set the event types when you create or update a webhook. At least one is required.

{
  "name": "SIEM-ingest-prod",
  "url": "https://siem.contoso.example/api/webhook",
  "eventTypes": [
    "incident.created.v1",
    "incident.status.changed.v1",
    "incident.assignee.changed.v1",
    "incident.comment.added.v1",
    "incident.closed.v1",
    "gamebook.run.v1"
  ],
  "monitoredAccountIds": [
    "11111111-1111-1111-1111-111111111111"
  ],
  "authenticationType": "Bearer",
  "token": "your-bearer-token",
  "signingToken": "your-hmac-signing-secret"
}

webhook.test.v1 is not subscribable. agent.investigation.completed.v1 must be listed here and selected on an Agent Configuration classification card before it delivers anything. Delivery outcomes for every event are visible per webhook under Settings → Developer Integrations, and through GET /webhooks/{id}/delivery-logs.

Questions about webhook events? Contact us at support@contraforce.com.

​Event Types

​Routing models

​The Delivery Envelope

​Request Headers

​Verifying the Signature

​webhook.test.v1

​incident.created.v1

​Fields

​Vendor identifiers

​Which blocks are present

​incident.closed.v1

​Fields

​incident.status.changed.v1

​Fields

​incident.assignee.changed.v1

​Fields

​incident.comment.added.v1

​Fields

​gamebook.run.v1

​Fields

​agent.investigation.completed.v1

​Fields

​Malicious score

​Delivery Rules

​Retries

​Event IDs

​Auto-disable

​Delivery logs

​Redelivery

​Requirements for your endpoint

​Subscribing

Event Types

Routing models

The Delivery Envelope

Request Headers

Verifying the Signature

`webhook.test.v1`

`incident.created.v1`

Fields

Vendor identifiers

Which blocks are present

`incident.closed.v1`

Fields

`incident.status.changed.v1`

Fields

`incident.assignee.changed.v1`

Fields

`incident.comment.added.v1`

Fields

`gamebook.run.v1`

Fields

`agent.investigation.completed.v1`

Fields

Malicious score

Delivery Rules

Retries

Event IDs

Auto-disable

Delivery logs

Redelivery

Requirements for your endpoint

Subscribing