fiberphp-ext/webhook

🪝 FiberPHP Webhook 组件 —— 事件驱动外部回调，支持 HMAC 签名、指数退避重试、异步投递，可靠投递。

dev-master 2026-08-23 06:58 UTC

Requires

• php: >=8.3
• ext-json: *
• fiberphp/framework: dev-master

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• PangBin

Published on Packagist.org on 2026-08-23 06:58 UTC

README

事件驱动外部回调，支持 HMAC 签名、指数退避重试、异步投递。

目录结构

src/
├── Webhook.php                # 统一入口
├── Signer.php                 # 签名器（HMAC-SHA256）
├── Dispatcher.php             # 派发器（同步/异步/重试）
├── Install.php                # 安装器（发布配置）
├── helpers.php                # 助手函数 webhook()
└── Model/
    ├── WebhookEndpoint.php    # 端点模型（URL + 事件订阅）
    └── WebhookDelivery.php    # 投递记录（状态 + 重试）
config/
└── webhook.php                # 配置文件
tests/
├── WebhookTest.php            # 9 个测试用例
└── bootstrap.php

安装

composer require fiberphp-ext/webhook

配置

config/webhook.php：

return [
    'timeout' => 10,
    'retries' => 3,
    'backoff' => [1, 5, 30],       // 重试间隔（秒）
    'signature' => [
        'header' => 'X-Webhook-Signature',
        'algorithm' => 'sha256',
    ],
    'queue' => true,               // 异步投递（需 fiberphp/queue）
];

快速开始

注册端点

// 注册一个 Webhook 端点
webhook()->register('https://example.com/webhook', [
    'events' => ['order.created', 'order.paid'],
    'secret' => 'whsec_xxx',
]);

派发事件

// 同步派发（等待所有端点响应）
webhook()->dispatch('order.created', ['order_id' => 123]);

// 异步派递（走队列，需 fiberphp/queue）
webhook()->dispatchAsync('order.created', ['order_id' => 123]);

接收方验签

// 接收方验证签名
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$secret = 'whsec_xxx';

if (webhook()->verify($payload, $signature, $secret)) {
    $data = json_decode($payload, true);
    // 处理事件
}

助手函数

webhook()->register($url, $events, $secret);
webhook()->dispatch($event, $payload);
webhook()->dispatchAsync($event, $payload);
webhook()->verify($payload, $signature, $secret);

工作机制

签名

• 算法：HMAC-SHA256
• 请求头：X-Webhook-Signature
• 签名内容：原始 payload body
• 接收方使用 hash_equals 常数时间比对

重试

• 失败后按 backoff 配置的间隔重试
• 默认重试 3 次，间隔 [1s, 5s, 30s]
• 指数退避策略

投递记录

每次投递生成 WebhookDelivery 记录，包含：

• endpoint：目标 URL
• event：事件名
• payload：负载数据
• status：HTTP 状态码
• success：是否成功
• attempts：尝试次数
• error：错误信息

API

Webhook

方法	说明
register($url, $events, $secret)	注册端点
dispatch($event, $payload)	同步派发
dispatchAsync($event, $payload)	异步派递
verify($payload, $signature, $secret)	验签

Signer

方法	说明
sign($payload, $secret)	生成 HMAC 签名
verify($payload, $signature, $secret)	验证签名

测试

composer install
./vendor/bin/phpunit

License

MIT