Introducing AI Jobs Webhooks: Real-Time Notifications for Your Application

Photo by Christina @ wocintechchat.com on Unsplash

In this article, we’ll guide you through setting up, enabling, and consuming SharpAPI webhooks in your application, complete with language-specific examples and tips to get the most out of this feature.

What Are AI Jobs Webhooks?

AI Jobs Webhooks are automated notifications sent from SharpAPI to your application whenever an AI job finishes processing. These notifications include all the relevant details about the job, such as its status, type, and any errors, wrapped in a signed and secure JSON payload.

Additionally, you can configure webhooks to include the AI job result directly in the payload for enhanced integration capabilities.

How to Set Up AI Jobs Webhooks

1. Enable Webhooks

Navigate to your Webhooks Management Dashboard in SharpAPI. Toggle the Enable Webhooks switch to turn on webhook notifications for your account.

2. Configure Your Webhook URL

Enter the URL of the endpoint where SharpAPI should send the webhook notifications. Ensure your endpoint is:

• Publicly accessible over HTTPS.
• Capable of receiving POST requests.
• Consistently returns a valid HTTP 200 status code.

3. Add Your Secret for Signature

Define a unique Secret for Signature. This secret is used to sign webhook payloads, ensuring that your application can verify the authenticity of each notification. Treat this secret like a password—keep it secure and update it only when necessary.

4. Include AI Job Result (Optional)

Check the Include AI Job Result box to include the result of the AI job directly in the webhook payload under the result parameter.

5. Save Your Configuration

Click SAVE, and your webhook settings are ready to go.

How SharpAPI AI Jobs Webhooks Work

Once webhooks are enabled, SharpAPI sends an HTTP POST request to your specified Webhook URL when an AI job is completed.

Here’s what the request includes:

• JSON Payload: This contains the job’s unique ID, its status, type.
• X-Signature Header: A cryptographic signature generated using HMAC SHA-256 with your secret.

Example User-Agent header for identifying webhook requests:

User-Agent: SharpAPIWebhook/1.0

Sample Webhook Payload

Without Job Result:

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

With Job Result Included:

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

Job-Level Custom Webhooks

If you want to configure webhook calls for individual AI jobs, you can use Job-Level Custom Webhooks. To enable this:

1. Include a Job-Webhook header with the webhook URL when dispatching the job.
2. This webhook will only execute for the specified job.

Make sure the provided URL meets these requirements:

• Publicly accessible over HTTPS.
• Capable of receiving POST requests.
• Consistently returns a 2XX HTTP status code.

Best Practices for Handling SharpAPI Webhooks

To ensure your application processes webhook notifications smoothly, follow these best practices:

1. Secure Your Webhook Endpoint

• Use HTTPS to encrypt all traffic between SharpAPI and your application.
• Validate the X-Signature Header for every request to confirm it originates from SharpAPI.

2. Log Incoming Requests

Maintain logs for every webhook call your application receives. Include details like timestamps, headers, and payloads to help with debugging or auditing.

3. Acknowledge Quickly

Respond with a 2xx HTTP status code as soon as you receive the webhook. If your processing logic is time-consuming, offload it to a background worker to keep your endpoint responsive.

4. Handle Retries Gracefully

SharpAPI retries webhook notifications up to three times in case of failures. Ensure your application can handle duplicate notifications without breaking.

5. Monitor Webhook Traffic

Monitor your endpoint’s performance and availability to ensure it can handle webhook traffic efficiently. Use tools like Sentry or New Relic for insights into potential bottlenecks.

Validating Webhook Signatures

To verify that a webhook notification comes from SharpAPI and hasn’t been tampered with, validate the X-Signature Header using the provided secret. Below are code examples for signature validation in four different programming languages:

PHP

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

if (hash_equals($computedSignature, $signature)) {
    // Signature is valid
} else {
    // Signature is invalid
}

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))) {
    // Signature is valid
} else {
    // Signature is invalid
}

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):
    # Signature is valid
else:
    # Signature is invalid

.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)) {
        // Signature is valid
    } else {
        // Signature is invalid
    }
}

For more information, visit our documentation or contact our support team.