Skip to main content

Notification Payload

Causely sends structured JSON payloads to all webhook-based integrations. Whether you're using Slack, Prometheus Alertmanager, Splunk On-Call, Microsoft Teams, or a custom system, the notification format below applies consistently.

Root Cause Detected​

The following payload is sent when Causely identifies a root cause (type: "ProblemDetected"):

{
  "link": "https://portal.causely.app/rootCauses/b55bd69c-7417-43c7-b1d0-1c06075fa63b",
  "name": "ImagePullErrors",
  "type": "ProblemDetected",
  "entity": {
    "id": "741d88ac-0d47-5f61-b9c1-2d7739a6ebf8",
    "link": "https://portal.causely.app/observe/topology/741d88ac-0d47-5f61-b9c1-2d7739a6ebf8",
    "name": "default/pull-error-demo-2",
    "type": "Controller"
  },
  "labels": {
    "k8s.cluster.uid": "8d92c7e7-db45-4267-a427-2fede28d1218",
    "k8s.cluster.name": "dev",
    "causely.ai/cluster": "dev",
    "k8s.namespace.name": "default",
    "k8s.controller.kind": "Deployment",
    "causely.ai/namespace": "default"
  },
  "objectId": "b55bd69c-7417-43c7-b1d0-1c06075fa63b",
  "severity": "Low",
  "timestamp": "2026-04-28T19:28:31.686364684Z",
  "description": {
    "details": "Image pull errors in Kubernetes often occur due to one of the following reasons:\n\n- **Invalid image name or tag**: The specified image name or tag does not exist in the registry, or has been incorrectly referenced.\n- **Image registry authentication issues**: The Kubernetes node may lack the necessary credentials (e.g., in a private registry) or permissions to pull the image.\n- **Network connectivity issues**: Kubernetes nodes might have restricted access to the internet or specific image registries, possibly due to firewall settings, proxy issues, or DNS misconfigurations.\n- **Rate limiting by image registries**: Some registries, such as Docker Hub, impose pull rate limits, which can prevent nodes from pulling images if exceeded.\n",
    "summary": "Kubernetes controllers may encounter image pull errors when they cannot download container images from a registry, causing Pods to fail in starting or remain in a `ImagePullBackOff` state. This disrupts the deployment of applications and can affect service availability.",
    "remediationOptions": [
      {
        "title": "Check Image Name and Tag",
        "description": "Verify that the image name and tag are correct and the image exists in your registry.\n"
      },
      {
        "title": "Configure ImagePullSecrets for Private Registries",
        "description": "If using a private registry, ensure an `ImagePullSecret` is correctly set up and assigned to the namespace or Pod:\n\n```bash\nkubectl create secret docker-registry myregistrykey \\\n  --docker-server=<registry-url> \\\n  --docker-username=<username> \\\n  --docker-password=<password> \\\n  --docker-email=<email>\n```\n\nAttach this secret to your Pod or namespace to provide credentials for image pulling.\n"
      }
    ]
  },
  "object_type": "defect"
}

Root Cause Cleared​

The following payload is sent when a previously detected root cause is resolved (type: "ProblemCleared"). It includes the same fields as the detected payload, plus duration_ns indicating how long the root cause was active:

{
  "link": "https://portal.causely.app/rootCauses/b55bd69c-7417-43c7-b1d0-1c06075fa63b",
  "name": "ImagePullErrors",
  "type": "ProblemCleared",
  "entity": {
    "id": "741d88ac-0d47-5f61-b9c1-2d7739a6ebf8",
    "link": "https://portal.causely.app/observe/topology/741d88ac-0d47-5f61-b9c1-2d7739a6ebf8",
    "name": "default/pull-error-demo-2",
    "type": "Controller"
  },
  "labels": {
    "k8s.cluster.uid": "8d92c7e7-db45-4267-a427-2fede28d1218",
    "k8s.cluster.name": "dev",
    "causely.ai/cluster": "dev",
    "k8s.namespace.name": "default",
    "k8s.controller.kind": "Deployment",
    "causely.ai/namespace": "default"
  },
  "objectId": "b55bd69c-7417-43c7-b1d0-1c06075fa63b",
  "severity": "Low",
  "timestamp": "2026-04-28T19:28:31.686364684Z",
  "description": {
    "details": "Image pull errors in Kubernetes often occur due to one of the following reasons:\n\n- **Invalid image name or tag**: The specified image name or tag does not exist in the registry, or has been incorrectly referenced.\n- **Image registry authentication issues**: The Kubernetes node may lack the necessary credentials (e.g., in a private registry) or permissions to pull the image.\n- **Network connectivity issues**: Kubernetes nodes might have restricted access to the internet or specific image registries, possibly due to firewall settings, proxy issues, or DNS misconfigurations.\n- **Rate limiting by image registries**: Some registries, such as Docker Hub, impose pull rate limits, which can prevent nodes from pulling images if exceeded.\n",
    "summary": "Kubernetes controllers may encounter image pull errors when they cannot download container images from a registry, causing Pods to fail in starting or remain in a `ImagePullBackOff` state. This disrupts the deployment of applications and can affect service availability.",
    "remediationOptions": [
      {
        "title": "Check Image Name and Tag",
        "description": "Verify that the image name and tag are correct and the image exists in your registry.\n"
      },
      {
        "title": "Configure ImagePullSecrets for Private Registries",
        "description": "If using a private registry, ensure an `ImagePullSecret` is correctly set up and assigned to the namespace or Pod:\n\n```bash\nkubectl create secret docker-registry myregistrykey \\\n  --docker-server=<registry-url> \\\n  --docker-username=<username> \\\n  --docker-password=<password> \\\n  --docker-email=<email>\n```\n\nAttach this secret to your Pod or namespace to provide credentials for image pulling.\n"
      }
    ]
  },
  "duration_ns": 601639777492,
  "object_type": "defect"
}

Payload Fields​

  • link: Direct URL to the root cause in the Causely portal.
  • name: The name of the root cause problem.
  • type: The type of notification. Either ProblemDetected (root cause identified) or ProblemCleared (root cause resolved).
  • entity: Details of the affected entity:
    • id: Unique identifier of the entity.
    • link: Direct URL to the entity in the Causely portal topology view.
    • name: Name of the entity.
    • type: Type of the entity (for example, Controller).
  • labels: Metadata providing additional context such as cluster name, namespace, and controller kind.
  • objectId: Unique identifier for the root cause problem.
  • severity: Severity level of the root cause (for example, Low, Medium, High, or Critical).
  • timestamp: The timestamp when the event occurred (ISO 8601 format).
  • description: Structured details about the root cause:
    • summary: A concise summary of the root cause and its impact.
    • details: A detailed explanation of the root cause, including possible contributing factors.
    • remediationOptions: A list of suggested remediation steps. Each item contains a title and a description.
  • duration_ns: (ProblemCleared only) The duration the root cause was active, in nanoseconds.
  • object_type: The type of object associated with the event (for example, defect).