Webhook Events

Reference for all outbound webhook event payloads that BlameTrail sends to your registered endpoints.

BlameTrail sends structured event payloads to your registered webhook endpoints when key events occur. This page documents the standard envelope format and all supported event types.

Configure webhook endpoints from Organization > Integrations > Webhooks. See Webhooks Overview for setup instructions.

Envelope format

Every webhook delivery uses a standard envelope structure:

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "incident.opened",
  "version": "1",
  "created_at": "2026-03-21T14:30:00.000Z",
  "tenant_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "data": { }
}

Field	Type	Description
`id`	string	A unique event identifier in the format `evt_<uuid>`. Use this to deduplicate deliveries.
`type`	string	The event type. See the sections below for all supported types.
`version`	string	The payload schema version. Currently `"1"`.
`created_at`	string	ISO 8601 timestamp of when the event was created.
`tenant_id`	string	UUID of the organization that owns this event.
`data`	object	The event-specific payload. Structure varies by event type.

Event types

incident.opened

Sent when a new incident is created after consecutive check failures.

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "incident.opened",
  "version": "1",
  "created_at": "2026-03-21T14:30:00.000Z",
  "tenant_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "data": {
    "incident_id": "d8f5a2b1-3c4e-4f6a-8b9c-1d2e3f4a5b6c",
    "title": "payments-api is down",
    "severity": "critical",
    "type": "availability",
    "status": "open",
    "started_at": "2026-03-21T14:28:00.000Z",
    "resolved_at": null,
    "duration_seconds": null,
    "service": {
      "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
      "name": "payments-api"
    },
    "monitor": {
      "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "name": "Health Check",
      "url": "https://api.example.com/health"
    }
  }
}

incident.acknowledged

Sent when a team member acknowledges an open incident.

{
  "id": "evt_b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "type": "incident.acknowledged",
  "version": "1",
  "created_at": "2026-03-21T14:35:00.000Z",
  "tenant_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "data": {
    "incident_id": "d8f5a2b1-3c4e-4f6a-8b9c-1d2e3f4a5b6c",
    "title": "payments-api is down",
    "severity": "critical",
    "type": "availability",
    "status": "acknowledged",
    "started_at": "2026-03-21T14:28:00.000Z",
    "resolved_at": null,
    "duration_seconds": null,
    "service": {
      "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
      "name": "payments-api"
    },
    "monitor": {
      "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "name": "Health Check",
      "url": "https://api.example.com/health"
    }
  }
}

incident.resolved

Sent when an incident is resolved, either automatically (after 3 consecutive passing checks) or manually.

{
  "id": "evt_c3d4e5f6-a7b8-9012-cdef-123456789012",
  "type": "incident.resolved",
  "version": "1",
  "created_at": "2026-03-21T14:45:00.000Z",
  "tenant_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "data": {
    "incident_id": "d8f5a2b1-3c4e-4f6a-8b9c-1d2e3f4a5b6c",
    "title": "payments-api is down",
    "severity": "critical",
    "type": "availability",
    "status": "resolved",
    "started_at": "2026-03-21T14:28:00.000Z",
    "resolved_at": "2026-03-21T14:44:30.000Z",
    "duration_seconds": 990,
    "service": {
      "id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
      "name": "payments-api"
    },
    "monitor": {
      "id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "name": "Health Check",
      "url": "https://api.example.com/health"
    }
  }
}

deploy.ingested

Sent when a deploy event is successfully processed via the Deploy Ingest API.

{
  "id": "evt_d4e5f6a7-b8c9-0123-defa-234567890123",
  "type": "deploy.ingested",
  "version": "1",
  "created_at": "2026-03-21T15:00:00.000Z",
  "tenant_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "data": {
    "deploy_id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "commit_sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
    "branch": "main",
    "environment": "production",
    "deployed_by": "github-actions",
    "service_id": "c1d2e3f4-a5b6-7890-abcd-ef1234567890"
  }
}

test.ping

Sent when you test a webhook endpoint from the integrations page.

{
  "id": "evt_e5f6a7b8-c9d0-1234-efab-345678901234",
  "type": "test.ping",
  "version": "1",
  "created_at": "2026-03-21T15:05:00.000Z",
  "tenant_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
  "data": {
    "message": "Webhook endpoint verified successfully.",
    "endpoint_id": "f6a7b8c9-d0e1-2345-fabc-456789012345"
  }
}

Incident data fields

All incident event types (incident.opened, incident.acknowledged, incident.resolved) share the same data structure:

Field	Type	Description
`incident_id`	string	UUID of the incident.
`title`	string	Human-readable incident title.
`severity`	string	Severity level: `critical`, `high`, `medium`, or `low`.
`type`	string	Incident type: `availability` or `latency`.
`status`	string	Current status: `open`, `acknowledged`, or `resolved`.
`started_at`	string	ISO 8601 timestamp of when the incident started.
`resolved_at`	string or null	ISO 8601 timestamp of resolution. Null for open and acknowledged incidents.
`duration_seconds`	number or null	Duration of the incident in seconds. Null until resolved.
`service`	object	The affected service: `{ id, name }`.
`monitor`	object or null	The monitor that detected the incident: `{ id, name, url }`. Null if the incident was not triggered by a monitor.

Delivery behavior

BlameTrail delivers webhooks over HTTPS using POST requests with a Content-Type: application/json header.
Each delivery includes the event payload as the request body.
Your endpoint should respond with a 2xx status code to acknowledge receipt.
Failed deliveries (non-2xx response or timeout) are retried with exponential backoff.

Next steps

Deploy Ingest API -- Send deploy events to BlameTrail.
Webhooks Overview -- Configure and manage webhook endpoints.

On this page