# Webhook reference

A webhook channel receives every alert as a JSON `POST`. Use it to open tickets, page someone, or feed your own dashboards.

## The request

- Method `POST`, header `Content-Type: application/json`.
- Sent from Radardue's servers to the HTTPS URL you saved.
- Any `2xx` response within 30 seconds counts as delivered. Anything else counts as a failure.

## Example

```json
{
  "event": "expiry.alert",
  "subject": "[Acme Dental] shop.acme-dental.com expires in 7 days",
  "text": "TLS certificate for shop.acme-dental.com (Acme Dental) expires in 7 days, on Mon 19 Oct 2026.\nIssuer/registrar: Let's Encrypt (R11)\n\nOpen in Radardue: https://radardue.com/app/items/42 …",
  "source": "radardue.com",
  "item": {
    "id": 42,
    "type": "certificate",
    "name": "shop.acme-dental.com",
    "port": 443,
    "client": "Acme Dental",
    "client_id": 7,
    "expires_at": "2026-10-19T09:12:44Z",
    "days_left": 7,
    "issuer": "Let's Encrypt (R11)",
    "url": "https://radardue.com/app/items/42"
  }
}
```

## Fields

| Field | Type | Description |
| --- | --- | --- |
| `event` | string | `expiry.alert` for real alerts, `test` for the Send test button. |
| `subject` | string | One-line summary, the same as the email subject. |
| `text` | string | Plain-text body, the same as the email body. |
| `source` | string | Always `radardue.com`. |
| `item.id` | number | Stable ID of the tracked item. |
| `item.type` | string | `certificate`, `domain` or `renewal`. |
| `item.name` | string | Hostname, domain, or the renewal's name. |
| `item.port` | number | Certificates only. The port that was checked. |
| `item.client` | string | Client name. |
| `item.client_id` | number | Stable ID of the client. |
| `item.expires_at` | string | Expiry time in UTC, RFC 3339. |
| `item.days_left` | number | Whole days until expiry; negative once expired. |
| `item.issuer` | string | Certificate issuer or domain registrar, when known. |
| `item.url` | string | Link to the item in Radardue. |

Test messages have `"event": "test"` and no `item`.

## Good to know

- **One item, several alerts.** An item alerts at each step of the [schedule](https://radardue.com/docs/alerts) and daily in its final week. If you open tickets, use `item.id` together with `item.expires_at` as the key so you update one ticket instead of creating new ones.
- **Securing your endpoint.** Requests aren't signed yet. Put a long random token in the URL path or query string and reject requests without it.
- **Stability.** We only ever add fields to this payload. Ignore fields you don't recognise.

Source: https://radardue.com/docs/webhooks