把提交发送到 Webhook，并重试接收端错过的内容

Webhook 会在几秒钟内把每条被接受的提交发送到你自己的 URL，这样一条线索就可以直接进入你的 CRM 或你自己的代码，而不用等电子邮件摘要。自 v1.0.0 起，Webhook 就是 FormFlow 的一部分。本教程添加一个端点，展示你的接收端会收到什么、如何检查，然后说明接收端宕机那天真正重要的部分：FormFlow 自己会重试什么，以及如何用“重试失败的投递”重新发送其余的内容。

你需要准备什么

一个你自己控制的接收端，能接受带有 JSON 请求体的 POST。它的地址必须是 https，而且只能解析到公网地址。保存时，面板会拒绝其他任何地址，所以 localhost 地址行不通，测试的常见方式是使用隧道。

添加端点

1. 在面板中打开表单，进入“投递”标签页。

2. 在“Webhook 端点”下，点击“添加端点”。

3. 让“发送为”保持为“FormFlow JSON（签名）”。另一个选项 Slack 消息需要一个 Slack 传入 Webhook 的 URL。

4. 把你接收端的地址粘贴到“端点 URL”中，并让“交付”保持打开。

5. 保存表单。一条标题为“立即复制您的 Webhook 签名密钥”的通知，会显示每个新端点的 URL 和密钥。它会一直停留在屏幕上，直到你关闭它，并且说明密钥不会再次显示。请把密钥存放到你的密钥管理器中。要获得新的密钥，请删除并重新添加该端点。

6. 在端点所在行点击“发送测试”。你会得到“测试已交付。”，或者“测试交付失败。”并附上你自己接收端的错误文字。该行必须先保存，而且该按钮限制每小时 20 次测试投递。

然后发送一条真实的提交，并在面板中打开它。它的“投递请求”表列出所有应收到该提交的目标，并显示状态（待处理、租赁、已投递或已终止）、尝试次数、投递 ID 和最后一次错误。

你的接收端会收到什么

每条非垃圾提交一个 POST。请求体是一份很小的 JSON 文档，附带三个标头。下面是它的结构，使用占位的值：

{
  "id": "SUBMISSION_UUID",
  "form": { "id": "FORM_UUID", "name": "Contact Us" },
  "submitted_at": "2026-10-08T09:00:00+00:00",
  "data": { "name": "Ada Lovelace", "email": "ada@example.com" }
}

• X-FormFlow-Timestamp 是尝试的时间，以秒为单位。

• X-FormFlow-Signature-256 是 sha256= 后面跟着对时间戳、一个点和原始请求体计算的 HMAC-SHA256，以端点的密钥为密钥。

• X-FormFlow-Delivery-Id 标识这次投递。在每次重试中它都保持不变。

在信任一个请求之前先验证签名，要对原始请求体验证，而不是对重新编码的副本。下面是 PHP 版本，形式与 FormFlow 的 API 文档所给一致：

function formflow_verify(string $rawBody, string $timestamp, string $signature, string $secret): bool
{
    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);

    return hash_equals($expected, $signature);
}

FormFlow 自己会重试什么

FormFlow 最多等待 10 秒获得回应。任何 2xx 响应都算作已投递。超时、连接中断、408、429 或 5xx 响应会被重试，总共最多六次尝试，每次之间的等待时间依次为 10 秒、1 分钟、5 分钟、30 分钟和 2 小时。任何其他回应，包括 3xx 或 4xx，都被视为永久拒绝，不会自动重试。FormFlow 不会跟随重定向，所以以重定向作答的端点算作失败。请把端点指向它的最终地址。

如果某个端点一直要求重试并用完了尝试次数，FormFlow 会为它关掉“交付”，并通过电子邮件通知团队的所有者。用完尝试次数的投递会显示为“已终止”。控制台也会持续列出转发已关闭的 Webhook，并显示它的连续失败次数，直到一次投递成功。

重试接收端错过的内容

在 v1.33 之前，每条错过的提交都需要单独的“立即重试”。现在点击一次就能覆盖一个端点。这个版本记录在更新日志中。顺序很重要：

1. 先修复接收端。每个失败的投递会再获得一次尝试，所以对仍然坏着的接收端重试，只会再次失败。

2. 在“投递”标签页上，检查端点的“交付”开关。如果 FormFlow 把它关掉了，请打开它并保存表单。对已关闭的端点重试会被拒绝，并提示“打开‘交付’并保存表单，然后重试。”

3. 在端点所在行点击“重试失败的投递”并确认。对话框会说明，每个仍可发送的失败投递都会重新排队，保留其原始投递 ID 和负载。

4. 一条通知会告诉你有多少条被重新排队。点击一次最多排队 500 条。如果还有剩余，它会提示你再点击一次。

5. 打开一条提交，查看它的“投递请求”表。尝试次数已经增加，状态应该达到“已投递”。

如果你更改了端点的 URL、密钥或格式，它会从头开始。更改之前发出的投递不会被重新发送，而从 v1.35.1 起，控制台不再把旧的失败算在新地址头上。在不做任何更改的情况下把端点关掉再打开，会保留它的失败记录。

需要了解的局限

• 新端点只接收在它设置完成之后到达的提交。不会把你已有的提交发给它。

• 垃圾邮件不会被转发。

• “重试失败的投递”只重新发送仍可发送的投递，而且只发送到端点当前的样子。

• 投递是至少一次。你的接收端必须能容忍重复。