AI 工作网络钩子：为您的应用程序提供实时通知

照片由Christina @ wocintechchat.com在Unsplash上拍摄

在本文中，我们将引导您在应用程序中设置、启用和使用SharpAPI Webhooks，并提供特定语言的示例和技巧，以充分利用此功能。

什么是AI Jobs Webhooks？

AI Jobs Webhooks是从SharpAPI发送到您的应用程序的自动通知，每当AI作业完成处理时。这些通知包含有关作业的所有相关详细信息，如其状态、类型和任何错误，并以签名和安全的JSON负载形式包装。

此外，您可以配置webhooks以将AI作业结果直接包含在负载中，以增强集成能力。

如何设置AI Jobs Webhooks

1. 启用Webhooks

导航到SharpAPI中的**Webhooks管理仪表板。切换启用Webhooks**开关以为您的帐户开启webhook通知。

2. 配置您的Webhook URL

输入SharpAPI应发送webhook通知的端点的URL。确保您的端点：

• 通过HTTPS公开可访问。
• 能够接收POST请求。
• 一致返回有效的HTTP 200状态代码。

3. 添加您的签名密钥

定义一个唯一的签名密钥。此密钥用于签署webhook负载，确保您的应用程序可以验证每个通知的真实性。将此密钥视为密码——保持其安全，仅在必要时更新。

4. 包括AI作业结果（可选）

勾选包括AI作业结果框，以将AI作业的结果直接包含在webhook负载中的result参数下。

5. 保存您的配置

点击保存，您的webhook设置即可准备就绪。

SharpAPI AI Jobs Webhooks的工作原理

一旦启用webhooks，当AI作业完成时，SharpAPI将发送HTTP POST请求到您指定的Webhook URL。

请求包括以下内容：

• JSON负载： 其中包含作业的唯一ID、状态、类型。
• X-Signature Header： 使用您的密钥生成的HMAC SHA-256加密签名。

识别webhook请求的示例User-Agent头：

User-Agent: SharpAPIWebhook/1.0

示例Webhook负载

没有作业结果：

{
    "id": "bf683177-3a48-47d1-9c4e-0b4de39517fa",
    "status": "success",
    "type": "content_translate"
}

包含作业结果：

{
    "id": "bf683177-3a48-47d1-9c4e-0b4de39517fa",
    "status": "success",
    "type": "content_translate",
    "result": {
        "content": "ciao",
        "from_language": "English",
        "to_language": "Italian"
    }
}

作业级自定义Webhooks

如果您想为单个AI作业配置webhook调用，可以使用作业级自定义Webhooks。要启用此功能：

1. 在调度作业时，包含带有webhook URL的Job-Webhook头。
2. 此webhook将仅针对指定作业执行。

确保提供的URL满足以下要求：

• 通过HTTPS公开可访问。
• 能够接收POST请求。
• 一致返回2XX HTTP状态代码。

处理SharpAPI Webhooks的最佳实践

为了确保您的应用程序顺利处理webhook通知，请遵循以下最佳实践：

1. 保护您的Webhook端点

• 使用HTTPS加密SharpAPI和您的应用程序之间的所有流量。
• 验证每个请求的X-Signature Header以确认其来自SharpAPI。

2. 记录传入请求

为您的应用程序接收到的每个webhook调用维护日志。包括时间戳、头和负载等详细信息，以帮助调试或审计。

3. 快速确认

一旦收到webhook，立即响应2xx HTTP状态代码。如果您的处理逻辑耗时，请将其卸载到后台工作者以保持端点响应。

4. 优雅地处理重试

SharpAPI在失败时最多重试三次webhook通知。确保您的应用程序可以处理重复通知而不崩溃。

5. 监控Webhook流量

监控您的端点性能和可用性，以确保其能够有效处理webhook流量。使用Sentry或New Relic等工具来获取潜在瓶颈的见解。

验证Webhook签名

要验证webhook通知来自SharpAPI并且未被篡改，请使用提供的密钥验证X-Signature Header。以下是四种编程语言中签名验证的代码示例：

PHP

$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? ''; 
$payload = file_get_contents('php://input'); 
$computedSignature = hash_hmac('sha256', $payload, $secret);

if (hash_equals($computedSignature, $signature)) {
    // 签名有效
} else {
    // 签名无效
}

JavaScript

const crypto = require('crypto');

const signature = req.headers['x-signature'] || '';
const payload = JSON.stringify(req.body);

const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

if (crypto.timingSafeEqual(Buffer.from(computedSignature), Buffer.from(signature))) {
    // 签名有效
} else {
    // 签名无效
}

Python

import hmac
import hashlib

signature = request.headers.get('X-Signature', '')
payload = request.get_data(as_text=True)

computed_signature = hmac.new(secret.encode(), payload.encode(), hashlib.sha256).hexdigest()

if hmac.compare_digest(computed_signature, signature):
    # 签名有效
else:
    # 签名无效

.NET

using System;
using System.IO;
using System.Security.Cryptography;
using System.Text;

string signature = Request.Headers["X-Signature"] ?? string.Empty; 
string payload;

using (var reader = new StreamReader(Request.Body, Encoding.UTF8))
{
    payload = await reader.ReadToEndAsync(); 
}

using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
{
    var computedSignatureBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));
    string computedSignature = BitConverter.ToString(computedSignatureBytes).Replace("-", "").ToLower();

    if (computedSignature.Equals(signature, StringComparison.OrdinalIgnoreCase)) {
        // 签名有效
    } else {
        // 签名无效
    }
}

有关更多信息，请访问我们的文档或联系我们的支持团队。