本文详解如何在 php 中正确接收 json 格式 webhook 请求、安全解析数据，并基于该数据发送 html 邮件，涵盖常见错误（如对象/数组访问混淆）、编码规范及生产环境注意事项。
本文详解如何在 php 中正确接收 json 格式 webhook 请求、安全解析数据，并基于该数据发送 html 邮件，涵盖常见错误（如对象/数组访问混淆）、编码规范及生产环境注意事项。
Webhook 是现代 API 集成中常用的数据推送机制，服务端需提供一个轻量、无状态的 HTTP 端点来接收外部系统（如 Stripe、Slack、Zapier）推送的结构化数据。当使用 PHP 实现 Webhook Listener 时，核心挑战在于：准确读取原始请求体、正确反序列化 JSON、安全提取字段，并可靠触发后续业务逻辑（如发信）。以下为完整、可直接部署的实践方案。
✅ 正确接收并解析 JSON Webhook 数据
Webhook 通常以 POST 方式发送 application/json 类型的请求体，此时 $_POST 为空（它仅处理 application/x-www-form-urlencoded 或 multipart/form-data），必须通过 php://input 流读取原始数据：
// 1. 获取原始 JSON 请求体
$jsonRaw = file_get_contents('php://input');
// 2. 验证请求是否为合法 JSON（非空且语法正确）
if (empty($jsonRaw)) {
http_response_code(400);
echo 'Error: Empty request body';
exit;
}
$data = json_decode($jsonRaw, true); // 第二参数 true → 返回关联数组（非 stdClass 对象）
// 3. 检查 JSON 解析是否成功
if (json_last_error() !== JSON_ERROR_NONE) {
error_log('Invalid JSON received: ' . json_last_error_msg());
http_response_code(400);
echo 'Error: Invalid JSON format';
exit;
}⚠️ 关键修正：原代码中 $action->email 是错误的——json_decode($json, true) 返回的是 关联数组，应使用 $data['email'] 访问；若需对象访问，则应省略 true 参数（即 json_decode($json)），但数组方式更安全、更符合 PHP 实践惯例。
✅ 安全提取字段并构建邮件内容
使用 isset() 和 filter_var() 进行基础校验，避免未定义索引或恶意输入：
立即学习“PHP免费学习笔记（深入）”；
$email = isset($data['email']) ? filter_var(trim($data['email']), FILTER_SANITIZE_EMAIL) : null;
$id = isset($data['id']) ? filter_var(trim($data['id']), FILTER_SANITIZE_STRING) : null;
$name = isset($data['name']) ? filter_var(trim($data['name']), FILTER_SANITIZE_STRING) : null;
// 必填字段校验
if (!$email || !$id || !$name || !filter_var($email, FILTER_VALIDATE_EMAIL)) {
http_response_code(400);
echo 'Error: Missing or invalid required fields (email, id, name)';
exit;
}✅ 发送结构化 HTML 邮件（含 UTF-8 支持）
原代码中存在两个关键问题：
- Content-type 使用了过时的 iso-8859-1 编码，而现代 HTML 邮件必须声明 UTF-8；
- 是 Cloudflare 邮箱保护伪标签，实际部署时需替换为真实邮箱。
修正后的邮件发送逻辑如下：
$to = $email;
$subject = "Hello {$name}! Your Diagnosis is ready";
$message = <<<HTML
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Hello {$name}!</title>
</head>
<body style="font-family: 'Roboto', 'Helvetica Neue', Helvetica, Arial, sans-serif; line-height: 1.6; color: #333;">
<h1 style="color: #2c3e50;">Hello {$name}!</h1>
<p>Your diagnosis ID is: <strong>{$id}</strong></p>
<p>We've processed your request successfully.</p>
</body>
</html>
HTML;
$headers = "MIME-Version: 1.0\r\n";
$headers .= "Content-Type: text/html; charset=UTF-8\r\n"; // ✅ 关键：UTF-8
$headers .= "From: Test <no-reply@example.com>\r\n";
$headers .= "Reply-To: no-reply@example.com\r\n";
$headers .= "X-Mailer: PHP/" . phpversion();
// 发送邮件（建议生产环境使用 PHPMailer 或 SMTP 服务提升可靠性）
if (mail($to, $subject, $message, $headers)) {
http_response_code(200);
echo 'OK: Email sent successfully';
} else {
error_log("Failed to send email to {$email}");
http_response_code(500);
echo 'Error: Failed to send notification';
}? 生产环境重要注意事项
- 安全性：始终验证 Content-Type: application/json 头（可选），对 email 字段严格过滤，防止邮件头注入（如 \r\n 注入）；
- 幂等性：Webhook 可能重试，建议记录 id 到数据库并去重处理；
- 日志与监控：记录所有入参、解析结果及邮件发送状态，便于排查；
- 替代方案：mail() 函数依赖本地 sendmail，推荐使用 PHPMailer 或 Symfony Mailer 集成 SMTP（如 SendGrid、Mailgun），确保送达率与可追溯性；
- HTTPS 强制：Webhook 端点必须启用 HTTPS，避免敏感数据明文传输。
通过以上结构化实现，你将获得一个健壮、安全、可维护的 PHP Webhook Listener，不仅能稳定接收 JSON 数据，还能可靠完成后续通知任务。
