# Actions

Source: https://www.pingtower.com/docs/service/actions/

A runbook action is an HTTP call the service makes for you when an alert opens. Restart the worker, open the ticket, flip the feature flag, before anyone wakes up.

```json
{
  "name": "restart-gateway-worker",
  "method": "POST",
  "url": "https://deploy.acme.example/api/services/gateway-worker/restart",
  "headers": { "Authorization": "Bearer …" },
  "body": "{\"reason\":\"pingtower\"}",
  "timeout_seconds": 10,
  "events": ["alert.opened"],
  "enabled": true
}
```

| Field | Meaning |
| --- | --- |
| `name` | Identity. Rules reference it by name or id. |
| `method` | `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. |
| `url` | http or https, up to 2048 characters. Private and loopback ranges are refused. |
| `headers` | Up to 32. Sealed at rest; reads return only `header_keys`. |
| `body` | Up to 8 KiB. Sealed at rest; reads return `has_body`. Send `""` to clear it, omit it to keep it. |
| `timeout_seconds` | 0 to 60, default 10. |
| `events` | `alert.opened`, `alert.escalated`, or both. Default `alert.opened`. |
| `enabled` | A disabled action is skipped silently. |

<span class="pill post">POST</span> <span class="pill get">GET</span> `/v1/projects/{id}/actions`, then <span class="pill get">GET</span> <span class="pill put">PUT</span> <span class="pill del">DELETE</span> `/v1/projects/{id}/actions/{aid}`.

## Wiring it to a rule

A rule's `actions` list names the actions to run. They fire when the alert opens, and again on each escalation for actions whose `events` include `alert.escalated`. The reference is checked when the rule is saved, and an action a rule still names cannot be deleted or renamed: `409` with the list of rules.

## Test and history

<span class="pill post">POST</span> `/v1/projects/{id}/actions/{aid}/test` fires it once, synchronously, with a synthetic alert, and records the result.

<span class="pill get">GET</span> `/v1/projects/{id}/actions/{aid}/executions?limit=` lists runs: `alert_id`, `event`, `status`, `status_code`, the first bytes of the response as `response_prefix`, `error`, `attempts`, `duration_ms`, `executed_at`. The app shows this under the action. Deleting an action keeps its execution rows.

<div class="docs-callout warn"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M8 2 1.5 13.5h13L8 2Z"/><path d="M8 6.5v3M8 11.5v.5"/></svg><div><span class="t">Idempotent endpoints only</span>An action can run more than once for one alert: on open, on every escalation it subscribed to, and on retry after a timeout. Point it at something that is safe to call twice.</div>
</div>