Notificaciones en tiempo real para tu aplicación

Foto de Christina @ wocintechchat.com en Unsplash

En este artículo, te guiaremos a través de la configuración, habilitación y consumo de webhooks de SharpAPI en tu aplicación, con ejemplos específicos de lenguaje y consejos para aprovechar al máximo esta función.

¿Qué son los Webhooks de AI Jobs?

Los Webhooks de AI Jobs son notificaciones automatizadas enviadas desde SharpAPI a tu aplicación cada vez que un trabajo de IA termina de procesarse. Estas notificaciones incluyen todos los detalles relevantes sobre el trabajo, como su estado, tipo y cualquier error, encapsulados en una carga útil JSON firmada y segura.

Además, puedes configurar webhooks para incluir el resultado del trabajo de IA directamente en la carga útil para mejorar las capacidades de integración.

Cómo configurar los Webhooks de AI Jobs

1. Habilitar Webhooks

Navega a tu Panel de Gestión de Webhooks en SharpAPI. Activa el interruptor de Habilitar Webhooks para activar las notificaciones de webhook para tu cuenta.

2. Configura tu URL de Webhook

Ingresa la URL del punto final donde SharpAPI debe enviar las notificaciones de webhook. Asegúrate de que tu punto final sea:

• Accesible públicamente a través de HTTPS.
• Capaz de recibir solicitudes POST.
• Que devuelva consistentemente un código de estado HTTP 200 válido.

3. Agrega tu Secreto para la Firma

Define un Secreto para la Firma único. Este secreto se utiliza para firmar las cargas útiles de los webhooks, asegurando que tu aplicación pueda verificar la autenticidad de cada notificación. Trata este secreto como una contraseña: mantenlo seguro y actualízalo solo cuando sea necesario.

4. Incluir Resultado del Trabajo de IA (Opcional)

Marca la casilla Incluir Resultado del Trabajo de IA para incluir el resultado del trabajo de IA directamente en la carga útil del webhook bajo el parámetro result.

5. Guarda tu Configuración

Haz clic en GUARDAR, y tu configuración de webhook estará lista.

Cómo funcionan los Webhooks de AI Jobs de SharpAPI

Una vez que los webhooks están habilitados, SharpAPI envía una solicitud HTTP POST a tu URL de Webhook especificada cuando se completa un trabajo de IA.

Esto es lo que incluye la solicitud:

• Carga útil JSON: Esto contiene el ID único del trabajo, su estado, tipo.
• Encabezado X-Signature: Una firma criptográfica generada usando HMAC SHA-256 con tu secreto.

Ejemplo de encabezado User-Agent para identificar solicitudes de webhook:

User-Agent: SharpAPIWebhook/1.0

Ejemplo de Carga Útil de Webhook

Sin Resultado del Trabajo:

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

Con Resultado del Trabajo Incluido:

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

Webhooks Personalizados a Nivel de Trabajo

Si deseas configurar llamadas de webhook para trabajos de IA individuales, puedes usar Webhooks Personalizados a Nivel de Trabajo. Para habilitar esto:

1. Incluye un encabezado Job-Webhook con la URL del webhook al enviar el trabajo.
2. Este webhook solo se ejecutará para el trabajo especificado.

Asegúrate de que la URL proporcionada cumpla con estos requisitos:

• Accesible públicamente a través de HTTPS.
• Capaz de recibir solicitudes POST.
• Que devuelva consistentemente un código de estado HTTP 2XX.

Mejores Prácticas para Manejar los Webhooks de SharpAPI

Para asegurar que tu aplicación procese las notificaciones de webhook sin problemas, sigue estas mejores prácticas:

1. Asegura tu Punto Final de Webhook

• Usa HTTPS para cifrar todo el tráfico entre SharpAPI y tu aplicación.
• Valida el Encabezado X-Signature para cada solicitud para confirmar que se origina en SharpAPI.

2. Registra las Solicitudes Entrantes

Mantén registros de cada llamada de webhook que reciba tu aplicación. Incluye detalles como marcas de tiempo, encabezados y cargas útiles para ayudar con la depuración o auditoría.

3. Reconoce Rápidamente

Responde con un código de estado HTTP 2xx tan pronto como recibas el webhook. Si tu lógica de procesamiento consume tiempo, descárgala a un trabajador en segundo plano para mantener tu punto final receptivo.

4. Maneja los Reintentos con Gracia

SharpAPI reintenta las notificaciones de webhook hasta tres veces en caso de fallos. Asegúrate de que tu aplicación pueda manejar notificaciones duplicadas sin romperse.

5. Monitorea el Tráfico de Webhook

Monitorea el rendimiento y la disponibilidad de tu punto final para asegurarte de que pueda manejar el tráfico de webhook de manera eficiente. Usa herramientas como Sentry o New Relic para obtener información sobre posibles cuellos de botella.

Validación de Firmas de Webhook

Para verificar que una notificación de webhook proviene de SharpAPI y no ha sido manipulada, valida el Encabezado X-Signature usando el secreto proporcionado. A continuación se muestran ejemplos de código para la validación de firmas en cuatro lenguajes de programación diferentes:

PHP

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

if (hash_equals($computedSignature, $signature)) {
    // La firma es válida
} else {
    // La firma no es válida
}

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 firma es válida
} else {
    // La firma no es válida
}

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 firma es válida
else:
    # La firma no es válida

.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 firma es válida
    } else {
        // La firma no es válida
    }
}

Para más información, visita nuestra documentación o contacta a nuestro equipo de soporte.