> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expira.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook alerts

> Receive Expira expiry alerts as JSON at your own HTTPS endpoint: the payload fields, event types, timeouts and retries.

A webhook channel sends each alert as a JSON `POST` to an HTTPS endpoint you choose. Use it to open tickets, page someone, or feed your own tooling.

## Connect a webhook

1. Go to **Alerts → Delivery** and open **Personal** or a team's tab.
2. Under **Delivery channels**, press **Connect** on **Webhook**.
3. Enter a **Name** and the **Endpoint URL**.
4. Save, then press **Test** to send a sample payload with `"test": true`.
5. Under **Alert preferences**, tick **Webhook** under **Via** and press **Save preferences**.

The endpoint must use `https` and be a public address: Expira refuses `localhost` and private network addresses.

## Payload

```json Example payload theme={null}
{
  "event": "asset.expiring",
  "test": false,
  "asset_id": "5b1f6c2e-8a3d-4f7b-9c21-7e4d2a9b6f10",
  "asset_name": "api.example.com",
  "asset_type": "ssl",
  "days_remaining": 7,
  "expiry_date": "2026-12-01",
  "org_id": "0e7c3a52-4b9d-4c8e-a1f3-2d6b8e9f0a14",
  "team_id": "c4a9e1d7-3f62-4b85-9e0a-6d1f2b7c8e53",
  "team_name": "Platform",
  "dashboard_url": "https://dashboard.expira.dev/dashboard/assets/5b1f6c2e-8a3d-4f7b-9c21-7e4d2a9b6f10"
}
```

| Field | Type | Notes |
| - | - | - |
| `event` | string | `asset.expiring`, or `asset.expired` once the expiry date has passed. |
| `test` | boolean | `true` only for alerts sent with the **Test** button. |
| `asset_id` | string | The asset's ID. Test alerts use `00000000-0000-0000-0000-000000000000`. |
| `asset_name` | string | The asset's name. |
| `asset_type` | string | One of `ssl`, `api_token`, `oauth_secret`, `iam_key`, `ssh_key`, `domain`, `code_signing`, `licence`. |
| `days_remaining` | number | Days until expiry. `0` means it expires today; negative means it has expired. |
| `expiry_date` | string | `YYYY-MM-DD`. |
| `org_id` | string | Your organisation's ID. |
| `team_id` | string or null | The team's ID, or `null` for a private asset. |
| `team_name` | string | The team's name, or "your team" when there's none. |
| `dashboard_url` | string | Link to the asset in the dashboard. |

The request has one header, `Content-Type: application/json`.

## Responses, timeouts and retries

* Any **2xx** response counts as delivered.
* Expira waits up to **10 seconds** for a response.
* **Redirects are not followed**: a 3xx response counts as a failure. Use the final URL.
* A failed delivery is retried on the next daily runs, up to 3 attempts in total. The error, with your URL removed, appears in [Alert history](https://docs.expira.dev/alerts/history.md).

## Securing your endpoint

Expira doesn't sign webhook requests. To make sure a request came from Expira, put a long random secret in the URL, for example `https://hooks.example.com/expira/3f9c…`, and reject requests that don't match. The URL is stored encrypted, like any other credential.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.