Webhook 自建服务器

把证书发送到您自己的服务器。您需要先准备一个接收程序：它接收本站发来的数据，再把证书安装到网站。网站首页、面板登录地址不能直接当作接收地址。

本站不会替您安装证书。接口返回成功，只说明接收程序报告收到了；网站是否已经用上新证书，要看接收程序有没有完成安装。

当前这张证书需要您手动推送。换证后自动推送是另一项设置：开启后，以后换证成功才会自动推送。系统里已经有的私钥不用重复上传；如果申请时只提交了 CSR，请先在证书详情上传对应私钥。

一、准备接收程序

1. 在您的公网服务器上准备一个能直接处理 POST 的地址，例如 https://deploy.example.com/nestssl/deploy，也可以使用 http:// 或自定义端口，如 http://203.0.113.10:8080/nestssl/deploy
2. 地址必须能从公网访问。内网、本机和云主机元数据地址不能使用
3. 接收程序要直接响应这个地址。如果返回跳转，本站不会跟着跳过去
4. HTTP 地址不加密，推送内容包含证书和私钥。服务器支持 HTTPS 后，请改成 HTTPS 地址。HTTPS 会校验证书，校验失败时不会自动改成 HTTP

二、填写地址

1. 打开 证书部署 → 自建 → Webhook → 新增目标
2. 填写名称和 接收地址
3. 验证密钥可以不填。填写后，接收程序里也要配置同样的密钥，用来核对请求是不是本站发出的
4. 保存。保存不会发送证书

三、测试连接

保存后，在目标上点击 测试连接。

测试的请求超时时间是 15 秒，不是固定要等满 15 秒。测试只发送一条不含证书和私钥的消息。看到「接口已响应」只说明地址有回应，不代表网站已经安装证书。

没有已签发证书时，还不能推送。可以先查看我的证书，或去申请证书。

四、选择证书并推送

1. 打开 关联与推送，选中要推送的证书
2. 勾选这个接收目标，点击 保存关联
3. 当前证书请点击 立即推送。推送成功后，记录里会写「证书已推送，接口返回成功」
4. 网站是否生效，请到服务器或浏览器里自行确认

换证后自动推送默认不开启。当前证书不会因为打开这个开关就立刻推送。开启并保存后，以后换证成功会自动推送。

正式推送的请求超时时间默认是 30 秒，不是固定要等满 30 秒。自动推送遇到普通失败时，最多发起 3 次，前两次大约间隔 30 秒和 120 秒。页面会写「等待重试」和预计时间，实际开始可能更晚。手动推送的普通失败不会自动再试；任务异常或执行过程中断时，系统仍可能再试，同样不超过 3 次。

五、检查结果

在证书详情的部署区域查看推送记录。记录里的状态包括：等待执行、执行中、等待重试、推送成功、推送失败、已取消、已跳过。

• 等待重试：系统还会再试。预计时间之后才会开始，实际开始可能更晚
• 推送失败：这一次已经结束。请修好接收地址或程序后重新推送，系统不会自动再试
• 已取消：尚未开始的任务被停止，或已经停止后续重试。请求已经发出但结果还不能确认时，会写明「本次请求结果未确认，后续重试已取消」，这不表示已经确认本次失败。已经明确失败的，仍保留失败结果。重新开启自动推送、重新关联或把地址改回去，都不会恢复已经取消的任务
• 发起请求次数只统计已经开始向外发送的次数。预检未通过时会写明请求未发出。若执行中断、无法确认对方是否收到，会写结果未确认
• 每次请求会留下当时的接收地址（已去掉账号、密码和查询参数）、HTTP 状态和时间。之后修改目标名称或地址，不会改写这些历史。更早、没有留下地址的记录会显示「历史接收地址未记录」
• 接口返回 2xx：本站记为成功，只说明接收程序报告成功
• 401 或 403：先核对验证密钥，再看接收程序的访问限制
• 对方未返回响应：确认接收程序已启动，并且地址可以直接访问。合法的 204 或空正文仍视为成功
• HTTPS 证书校验失败：检查的是接收服务器自己的证书，不是本站这次证书申请失败

六、常见问题

必须先测试才能保存或推送吗？ 不用。测试用来确认地址，保存和推送不依赖测试结果。

关闭自动推送后，已经排队的任务会怎样？ 尚未开始的自动推送会取消。发送前发现已经关闭，也会停止这次请求。停止操作可能恰好遇上请求发出，已经发出的请求不能撤回；如果失败，也不会再自动重试。重新开启不会继续这些旧任务。取消关联、停用目标，或修改接收地址、验证密钥，也会取消尚未开始的对应任务。只改名称、密钥留空不修改、或原样保存，不会取消。

修改地址后，旧记录里的地址会变吗？ 不会。每条请求保留当时实际使用的地址摘要。没有记录地址的旧数据会显示「历史接收地址未记录」，不会用现在的地址填回去。

可以用网站首页吗？ 不可以。接收地址要由接收程序直接处理。

七、请求协议

下面是接收程序需要识别的字段。字段名保持不变。

本站发送 POST，正文为 JSON。验证密钥只放在请求头 X-NestSSL-Token，不放进 JSON。

事件

请求头

POST /nestssl/deploy HTTP/1.1
Host: deploy.example.com
Content-Type: application/json
User-Agent: NestSSL-CertDeploy/1.0
X-NestSSL-Event: certificate.deploy
X-NestSSL-Token: your-secret-token

测试连接示例

{
    "event": "certificate.deploy.test",
    "message": "NestSSL 部署目标连通性测试",
    "timestamp": "2026-05-29T10: 30: 00+08: 00"
}

正式推送示例

trigger 的取值：

{
    "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"
}

PEM 里的换行在 JSON 中写成 \n。任意 2xx 都视为接口报告成功，不要求固定的 JSON 回执。

地址限制

各环境都允许公网 http:// 和 https://，包括合法自定义端口。

仍然拒绝：地址中的用户名或密码、本机名、内网、回环、链路本地、组播、未指定、文档、基准测试和保留地址。域名的全部解析结果都必须是公网地址，解析失败则拒绝。连接会固定到已核对的地址，避免后来的解析结果被调包。不会自动跟随跳转。HTTPS 继续校验证书。

私钥和验证密钥不会写入应用日志或错误提示。

八、PHP 与 Nginx 接收示例

下载 PHP 与 Nginx 接收示例。压缩包里是接收程序、配置模板和说明，解压后按包内 README 安装。它不经过本站路由，也不依赖 Laravel。适用环境是 Linux 本地文件系统、PHP 8.3 及以上、OpenSSL、PHP-FPM 和 Nginx。它不是宝塔或其他面板的通用插件。

下面这些名字都要换成你自己的：

按这个顺序做：

1. 放置 public/index.php，先只启用 HTTP 接收入口。这个入口不引用证书文件。
2. 在配置里写上允许的域名、固定证书目录和验证密钥。密钥在这个示例里必须填写，并用 hash_equals 比对请求头 X-NestSSL-Token。本站后台仍允许把验证密钥留空。
3. 用专用用户运行新增的 PHP-FPM 池，不要停用原来的池。服务已在运行时重载它，不要再启动一个 php-fpm。配置放在 /etc/nestssl-webhook/receiver.php，证书和私钥放在 /var/lib/nestssl-webhook。这两处都在网站目录外面。按 README 安装脚本和 sudoers，保留默认的重载入口；脚本归 root，权限为 0755，运行用户不能修改它。
4. 在 NestSSL 填写接收地址并测试连接。测试只看接口是否返回成功，不写证书，也不检查或重载 Nginx。
5. 推送证书。接收程序核对证书、私钥和域名后，把一对文件放进版本目录，再执行固定的重载脚本。
6. 确认 current 已经出现后，再启用使用这些文件的 HTTPS 配置，然后由管理员执行 nginx -t && nginx -s reload，检查并重载 Nginx。
7. 打开网站，或用 openssl x509 -noout -serial -fingerprint -sha256 确认序列号和指纹已经换成新证书。

首次 HTTP 接收时还没有证书文件，不要写 ssl_certificate。文件不存在时 nginx -t 会失败。这个 HTTP 入口用来测试连接，并接收第一次推送。

首次启用 HTTPS 发生在 current 出现之后：由管理员把网站配置指到 证书目录/current/fullchain.pem 和 privkey.pem，再执行 nginx -t && nginx -s reload。只检查配置还不会让网站启用 HTTPS。

以后换证由接收程序切换文件并重载。管理员再用序列号或指纹确认网站。接收程序负责第 4 步的测试响应，以及第 5 步的校验、写入、切换和重载命令。

接收地址如果使用 http://，证书和私钥会以明文传输。只在你接受这个风险，或接收地址只在可信网络里可达时使用。这个示例只有在文件更新、检查和重载命令完成后才返回 2xx；不表示浏览器一定已经用上新证书。每次正式推送都会检查并重载，包括重复推送同一份证书。需要回到旧证书时，重新推送那个版本即可。当前协议没有投递序号，不能据此识别所有乱序请求。

本站等待正式推送的时间默认是 30 秒，测试连接是 15 秒。接收地址不要先返回 301 或 302，本站不跟随跳转。401 或 403 先核对验证密钥和文件权限。404 或 405 说明地址没有交到这个 PHP 入口，或入口不接受 POST。

接收程序失败时返回非 2xx，本站显示 HTTP 状态。接收服务器的 /var/lib/nestssl-webhook/receiver.log 会记录状态码、拒绝原因和重载结果；日志无法写入时，查看服务器配置的 PHP-FPM 或 Nginx 错误日志。日志不保存重载脚本的原始输出。遇到 Nginx 检查或重载失败，请管理员执行 sudo /usr/sbin/nginx -t，查看具体的配置文件和行号；此命令只检查，不会重载。

程序会尝试恢复原证书，恢复失败会报错；推送的就是当前版本时，不再重复恢复重载。无法确认上次重载是否结束时，按 README 的排错说明处理，再重新推送。

配置、私钥和状态都放在 Web 根之外，私钥权限是 0600。请求不能指定目录、命令，也不能打开测试模式。

本地检查示例：解压后在示例目录执行 php tests/run.php。它不需要 Docker，只用临时证书和模拟重载，不安装到这台服务器。

相关文档

• 部署总览
• 下载与安装