Webhook
通过 Webhook 将证书推送到您自建的 HTTPS 接口，适合自有服务器、自动化运维脚本或面板对接。请求会包含证书链与私钥，请只填写您自己控制的公网地址。
一、准备接收地址
- 在服务器上提供一个可公网访问的 URL，例如：
https://your-server.example.com:8443/nestssl/deploy（允许合法自定义端口） - 接口需对 POST 请求返回 HTTP 2xx，本站才视为部署成功
- 若接口返回 3xx，本站不会跟随重定向，请直接填写最终接收地址
二、在本站配置
- 证书部署 → 左侧 自建 → Webhook → 「+ 新增目标」
- 填写 Webhook URL（生产须为
https；开发环境可用http） - 验证字符串（选填）：固定令牌，本站通过请求头透传，供您的程序校验
- 点击 「测试」 确认能收到测试事件 → 保存
- 在证书详情 上传私钥（Webhook 部署强制要求私钥）
- 到 关联与推送 为证书勾选该目标（可选 自动）
三、请求说明
本站向您的 URL 发送 POST 请求，Body 为 JSON。
事件类型
| event 值 | 说明 |
|---|---|
certificate.deploy.test |
测试连接（不含证书、私钥） |
certificate.deploy |
正式部署（含证书链与私钥） |
请求头
每次请求均包含以下 HTTP 头：
| 请求头 | 说明 |
|---|---|
Content-Type |
固定为 application/json |
User-Agent |
NestSSL 出站标识 |
X-NestSSL-Event |
与 JSON 中 event 字段一致 |
X-NestSSL-Token |
若配置了验证字符串则携带；不会写入 JSON 正文 |
示例：
POST /nestssl/deploy HTTP/1.1
Host: your-server.example.com
Content-Type: application/json
User-Agent: NestSSL-CertDeploy/1.0
X-NestSSL-Event: certificate.deploy
X-NestSSL-Token: your-secret-token
请在接收端校验 X-NestSSL-Token（若已配置），防止未授权调用。
JSON 请求示例
测试连接（certificate.deploy.test）
点击部署目标的「测试」时发送：
JSON
{
"event": "certificate.deploy.test",
"message": "NestSSL 部署目标连通性测试",
"timestamp": "2026-05-29T10: 30: 00+08: 00"
}正式部署（certificate.deploy）
证书签发、重签或手动部署时发送。trigger 取值：
| 值 | 含义 |
|---|---|
issued |
首次签发后自动推送 |
reissued |
重签后自动推送 |
manual |
在关联与推送或证书详情手动推送 |
JSON
{
"event": "certificate.deploy",
"trigger": "manual",
"certificate_id": 42,
"domain": "www.example.com",
"fingerprint": "a1b2c3d4e5f6...",
"issued_at": "2026-05-29",
"expires_at": "2026-12-15",
"certificate_pem": "-----BEGIN CERTIFICATE-----\nMIIF...\n-----END CERTIFICATE-----\n",
"ca_bundle_pem": "-----BEGIN CERTIFICATE-----\nMIIE...\n-----END CERTIFICATE-----\n",
"fullchain_pem": "-----BEGIN CERTIFICATE-----\nMIIF...\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIE...\n-----END CERTIFICATE-----\n",
"private_key_pem": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----\n"
}字段说明：
| 字段 | 类型 | 说明 |
|---|---|---|
event |
string | 固定为 certificate.deploy |
trigger |
string | 触发方式：issued / reissued / manual |
certificate_id |
int | 本站证书记录 ID |
domain |
string | 证书域名 |
fingerprint |
string | 证书指纹（SHA-256） |
issued_at |
string | null | 签发日期，YYYY-MM-DD |
expires_at |
string | null | 到期日期，YYYY-MM-DD |
certificate_pem |
string | 站点证书 PEM |
ca_bundle_pem |
string | null | CA 中间证书链 PEM |
fullchain_pem |
string | 站点证书 + CA 链拼接 PEM |
private_key_pem |
string | 私钥 PEM（正式部署必有；无私钥时不会发起请求） |
PEM 字段中的换行在 JSON 里以
\n转义。
四、接收端示例逻辑
- 校验
X-NestSSL-Token（若已配置） - 解析 JSON，写入 Nginx/Apache 证书路径
- 执行
reload或重启服务 - 返回
200 OK
本站 不会 代为在您的服务器上安装证书，仅负责推送数据。
五、安全说明
- 生产环境必须使用 HTTPS（本站会拒绝 HTTP Webhook）
- 禁止 URL 中的用户名/密码、localhost、私网、回环、链路本地、云元数据及不可公网路由地址
- 域名的全部 A/AAAA 解析结果都必须为安全公网地址；混合公网/私网会被拒绝
- DNS 解析失败时拒绝配置/出站，并返回中文错误
- 本站不会自动跟随 3xx 重定向
- 配置验证字符串并校验请求头
X-NestSSL-Token - 私钥不会写入本站应用日志或连通性测试载荷
- 私钥写入文件时设置适当文件权限（如
600）