KI-Jobs-Webhooks: Echtzeitbenachrichtigungen für Ihre Anwendung

Foto von Christina @ wocintechchat.com auf Unsplash

In diesem Artikel führen wir Sie durch das Einrichten, Aktivieren und Verwenden von SharpAPI-Webhooks in Ihrer Anwendung, einschließlich sprachspezifischer Beispiele und Tipps, um das Beste aus dieser Funktion herauszuholen.

Was sind AI Jobs Webhooks?

AI Jobs Webhooks sind automatisierte Benachrichtigungen, die von SharpAPI an Ihre Anwendung gesendet werden, wenn ein KI-Job die Verarbeitung abgeschlossen hat. Diese Benachrichtigungen enthalten alle relevanten Details zum Job, wie dessen Status, Typ und etwaige Fehler, eingebettet in eine signierte und sichere JSON-Nutzlast.

Darüber hinaus können Sie Webhooks so konfigurieren, dass das Ergebnis des KI-Jobs direkt in die Nutzlast für verbesserte Integrationsmöglichkeiten aufgenommen wird.

Wie man AI Jobs Webhooks einrichtet

1. Webhooks aktivieren

Navigieren Sie zu Ihrem Webhooks Management Dashboard in SharpAPI. Schalten Sie den Enable Webhooks Schalter um, um Webhook-Benachrichtigungen für Ihr Konto zu aktivieren.

2. Ihre Webhook-URL konfigurieren

Geben Sie die URL des Endpunkts ein, an den SharpAPI die Webhook-Benachrichtigungen senden soll. Stellen Sie sicher, dass Ihr Endpunkt:

• Öffentlich über HTTPS zugänglich ist.
• In der Lage ist, POST-Anfragen zu empfangen.
• Konsistent einen gültigen HTTP 200 Statuscode zurückgibt.

3. Ihr Geheimnis für die Signatur hinzufügen

Definieren Sie ein einzigartiges Geheimnis für die Signatur. Dieses Geheimnis wird verwendet, um Webhook-Nutzlasten zu signieren und sicherzustellen, dass Ihre Anwendung die Authentizität jeder Benachrichtigung überprüfen kann. Behandeln Sie dieses Geheimnis wie ein Passwort – halten Sie es sicher und aktualisieren Sie es nur bei Bedarf.

4. AI Job Ergebnis einschließen (optional)

Aktivieren Sie das Kontrollkästchen AI Job Ergebnis einschließen, um das Ergebnis des KI-Jobs direkt in die Webhook-Nutzlast unter dem Parameter result aufzunehmen.

5. Ihre Konfiguration speichern

Klicken Sie auf SAVE, und Ihre Webhook-Einstellungen sind bereit.

Wie SharpAPI AI Jobs Webhooks funktionieren

Sobald Webhooks aktiviert sind, sendet SharpAPI eine HTTP-POST-Anfrage an Ihre angegebene Webhook-URL, wenn ein KI-Job abgeschlossen ist.

Hier ist, was die Anfrage enthält:

• JSON-Nutzlast: Diese enthält die eindeutige ID des Jobs, dessen Status, Typ.
• X-Signature-Header: Eine kryptografische Signatur, die mit HMAC SHA-256 und Ihrem Geheimnis generiert wurde.

Beispiel für den User-Agent-Header zur Identifizierung von Webhook-Anfragen:

User-Agent: SharpAPIWebhook/1.0

Beispiel für eine Webhook-Nutzlast

Ohne Job-Ergebnis:

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

Mit Job-Ergebnis enthalten:

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

Job-Level Custom Webhooks

Wenn Sie Webhook-Anrufe für einzelne KI-Jobs konfigurieren möchten, können Sie Job-Level Custom Webhooks verwenden. Um dies zu aktivieren:

1. Fügen Sie einen Job-Webhook-Header mit der Webhook-URL hinzu, wenn Sie den Job senden.
2. Dieser Webhook wird nur für den angegebenen Job ausgeführt.

Stellen Sie sicher, dass die angegebene URL diese Anforderungen erfüllt:

• Öffentlich über HTTPS zugänglich.
• In der Lage, POST-Anfragen zu empfangen.
• Konsistent gibt einen 2XX HTTP-Statuscode zurück.

Best Practices für den Umgang mit SharpAPI Webhooks

Um sicherzustellen, dass Ihre Anwendung Webhook-Benachrichtigungen reibungslos verarbeitet, befolgen Sie diese Best Practices:

1. Sichern Sie Ihren Webhook-Endpunkt

• Verwenden Sie HTTPS, um den gesamten Datenverkehr zwischen SharpAPI und Ihrer Anwendung zu verschlüsseln.
• Validieren Sie den X-Signature-Header für jede Anfrage, um zu bestätigen, dass sie von SharpAPI stammt.

2. Eingehende Anfragen protokollieren

Führen Sie Protokolle für jeden Webhook-Anruf, den Ihre Anwendung erhält. Fügen Sie Details wie Zeitstempel, Header und Nutzlasten hinzu, um bei der Fehlerbehebung oder Prüfung zu helfen.

3. Schnell bestätigen

Antworten Sie mit einem 2xx HTTP-Statuscode, sobald Sie den Webhook erhalten. Wenn Ihre Verarbeitung zeitaufwändig ist, verlagern Sie sie in einen Hintergrundarbeiter, um Ihren Endpunkt reaktionsfähig zu halten.

4. Wiederholungen ordentlich handhaben

SharpAPI wiederholt Webhook-Benachrichtigungen bis zu dreimal im Falle von Fehlern. Stellen Sie sicher, dass Ihre Anwendung doppelte Benachrichtigungen verarbeiten kann, ohne zu brechen.

5. Überwachen Sie den Webhook-Verkehr

Überwachen Sie die Leistung und Verfügbarkeit Ihres Endpunkts, um sicherzustellen, dass er den Webhook-Verkehr effizient verarbeiten kann. Verwenden Sie Tools wie Sentry oder New Relic, um Einblicke in mögliche Engpässe zu erhalten.

Validierung von Webhook-Signaturen

Um zu überprüfen, dass eine Webhook-Benachrichtigung von SharpAPI stammt und nicht manipuliert wurde, validieren Sie den X-Signature-Header mit dem bereitgestellten Geheimnis. Unten finden Sie Codebeispiele zur Signaturvalidierung in vier verschiedenen Programmiersprachen:

PHP

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

if (hash_equals($computedSignature, $signature)) {
    // Signatur ist gültig
} else {
    // Signatur ist ungültig
}

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))) {
    // Signatur ist gültig
} else {
    // Signatur ist ungültig
}

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):
    # Signatur ist gültig
else:
    # Signatur ist ungültig

.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)) {
        // Signatur ist gültig
    } else {
        // Signatur ist ungültig
    }
}

Für weitere Informationen besuchen Sie unsere Dokumentation oder kontaktieren Sie unser Support-Team.