Send alerts with the private webhook

Get the ingest URL and key

1. Open Webhook generator as an Admin.
2. Copy the Ingest URL.
3. Copy the API Key.
4. Store the key in your secret manager rather than in source control.

Send a request

Send the alert as a POST request with the API key in the X-Shankh-Key header.

Every field is optional — there is no schema validation. Shankh reads the first key it recognises from each group below, so most existing alert payloads work unchanged.

POST <ingest-url>
Content-Type: application/json
X-Shankh-Key: <your-api-key>

{
  "title": "Checkout latency above threshold",
  "description": "p95 latency 2.4s over 5 minutes",
  "severity": "high",
  "service": "checkout-api",
  "workspace": "payments",
  "source": "custom-monitor"
}

Set the severity

Severity is mapped from a wide vocabulary onto Shankh's four levels — sev1, p1, firing and down all become CRITICAL, for example. Anything unrecognised becomes INFO.

Know which workspace it lands in

Shankh resolves the workspace in this order and stops at the first match:

1. The workspace named in the alarm metadata.
2. A cloud resource whose display name matches the service — exact match first, then substring.
3. The workspace of whoever is currently on call.
4. The organisation's oldest workspace.

Close an incident from the same sender

Send the recovery with is_recovery set to true. Shankh matches it to the open incident by correlation key:

correlation_key = sha256(organisation | service_name | metric_name)

A separate dedup hash of source, service, title and severity suppresses duplicate alerts inside a 5-minute window. It only suppresses — it never resolves anything.

Read the response

A created incident returns 201 with the payload wrapped in a success envelope. Response keys are camelCase — incidentId, not incident_id.

201 Created
{ "success": true, "data": { "incidentId": "…" } }

Errors are not wrapped in that envelope. They return success false alongside statusCode, message, errors, timestamp and path — so a client that only reads data sees nothing at all on failure.

Verify that an incident was created

1. Open Incidents and filter to the workspace you sent to.
2. Confirm a new incident appears with the expected title, service and severity.
3. Confirm the incident source shows the webhook sender.
4. Confirm the assigned responder received a notification.

Rotate the key

1. Prepare every sender to take a new key.
2. Regenerate the key in Webhook generator.
3. Update all senders immediately.
4. Send a test request and confirm a new incident appears.