Webhooks AI Emplois : Notifications en temps réel pour votre application

Photo par Christina @ wocintechchat.com sur Unsplash

Dans cet article, nous vous guiderons à travers la configuration, l'activation et la consommation des webhooks SharpAPI dans votre application, avec des exemples spécifiques à chaque langage et des conseils pour tirer le meilleur parti de cette fonctionnalité.

Que sont les Webhooks des Jobs AI ?

Les Webhooks des Jobs AI sont des notifications automatiques envoyées de SharpAPI à votre application chaque fois qu'un job AI termine son traitement. Ces notifications incluent tous les détails pertinents sur le job, tels que son statut, son type, et toute erreur, enveloppés dans une charge utile JSON signée et sécurisée.

De plus, vous pouvez configurer les webhooks pour inclure directement le résultat du job AI dans la charge utile pour des capacités d'intégration améliorées.

Comment configurer les Webhooks des Jobs AI

1. Activer les Webhooks

Naviguez vers votre Tableau de bord de gestion des Webhooks dans SharpAPI. Activez l'interrupteur Activer les Webhooks pour activer les notifications de webhook pour votre compte.

2. Configurer votre URL de Webhook

Entrez l'URL de l'endpoint où SharpAPI doit envoyer les notifications de webhook. Assurez-vous que votre endpoint est :

• Accessible publiquement via HTTPS.
• Capable de recevoir des requêtes POST.
• Retourne systématiquement un code de statut HTTP 200 valide.

3. Ajouter votre secret pour la signature

Définissez un Secret pour la signature unique. Ce secret est utilisé pour signer les charges utiles des webhooks, garantissant que votre application peut vérifier l'authenticité de chaque notification. Traitez ce secret comme un mot de passe—gardez-le sécurisé et mettez-le à jour uniquement si nécessaire.

4. Inclure le résultat du Job AI (Optionnel)

Cochez la case Inclure le résultat du Job AI pour inclure le résultat du job AI directement dans la charge utile du webhook sous le paramètre result.

5. Enregistrez votre configuration

Cliquez sur ENREGISTRER, et vos paramètres de webhook sont prêts à être utilisés.

Comment fonctionnent les Webhooks des Jobs AI de SharpAPI

Une fois les webhooks activés, SharpAPI envoie une requête HTTP POST à l'URL de Webhook spécifiée lorsque qu'un job AI est terminé.

Voici ce que la requête inclut :

• Charge utile JSON : Celle-ci contient l'ID unique du job, son statut, son type.
• En-tête X-Signature : Une signature cryptographique générée à l'aide de HMAC SHA-256 avec votre secret.

Exemple d'en-tête User-Agent pour identifier les requêtes de webhook :

User-Agent: SharpAPIWebhook/1.0

Exemple de Charge utile de Webhook

Sans Résultat du Job :

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

Avec Résultat du Job Inclus :

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

Webhooks personnalisés au niveau du Job

Si vous souhaitez configurer des appels de webhook pour des jobs AI individuels, vous pouvez utiliser des Webhooks personnalisés au niveau du Job. Pour activer cela :

1. Incluez un en-tête Job-Webhook avec l'URL du webhook lors de l'envoi du job.
2. Ce webhook ne s'exécutera que pour le job spécifié.

Assurez-vous que l'URL fournie répond à ces exigences :

• Accessible publiquement via HTTPS.
• Capable de recevoir des requêtes POST.
• Retourne systématiquement un code de statut HTTP 2XX.

Bonnes pratiques pour gérer les Webhooks de SharpAPI

Pour vous assurer que votre application traite les notifications de webhook sans problème, suivez ces bonnes pratiques :

1. Sécurisez votre endpoint de Webhook

• Utilisez HTTPS pour crypter tout le trafic entre SharpAPI et votre application.
• Validez l'En-tête X-Signature pour chaque requête afin de confirmer qu'elle provient de SharpAPI.

2. Journalisez les requêtes entrantes

Tenez un journal de chaque appel de webhook que votre application reçoit. Incluez des détails tels que les horodatages, les en-têtes et les charges utiles pour aider au débogage ou à l'audit.

3. Accusez réception rapidement

Répondez avec un code de statut HTTP 2xx dès que vous recevez le webhook. Si votre logique de traitement est chronophage, déchargez-la vers un travailleur en arrière-plan pour garder votre endpoint réactif.

4. Gérez les réessais avec grâce

SharpAPI réessaye les notifications de webhook jusqu'à trois fois en cas d'échec. Assurez-vous que votre application peut gérer les notifications en double sans problème.

5. Surveillez le trafic de Webhook

Surveillez la performance et la disponibilité de votre endpoint pour vous assurer qu'il peut gérer efficacement le trafic de webhook. Utilisez des outils comme Sentry ou New Relic pour des informations sur les éventuels goulots d'étranglement.

Validation des signatures de Webhook

Pour vérifier qu'une notification de webhook provient de SharpAPI et n'a pas été altérée, validez l'En-tête X-Signature en utilisant le secret fourni. Voici des exemples de code pour la validation de la signature dans quatre langages de programmation différents :

PHP

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

if (hash_equals($computedSignature, $signature)) {
    // La signature est valide
} else {
    // La signature est invalide
}

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))) {
    // La signature est valide
} else {
    // La signature est invalide
}

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):
    # La signature est valide
else:
    # La signature est invalide

.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)) {
        // La signature est valide
    } else {
        // La signature est invalide
    }
}

Pour plus d'informations, visitez notre documentation ou contactez notre équipe de support.