Introduction to Callbacks (Webhooks)

Callbacks, also known as webhooks, are user-defined HTTP callbacks that allow real-time notifications of events happening within a system. In the context of superAI, webhooks enable users to receive updates about the status of their jobs, such as when a job is completed. Instead of constantly polling the superAI API to check the job status, users can provide a callback URL, which superAI will send a POST request to once the job is done.

How Webhooks Work in super.AI

In superAI, webhooks are triggered upon job submission. Users can provide a callbackUrl in the payload when submitting a job. When the job is completed, superAI will send a POST request to the specified callbackUrl with the job details.

Here's an example of a job submission with a callbackUrl:

curl "https://api.super.ai/v1/apps/<project_uuid>/jobs" \
-X POST \
-H "API-KEY: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{ "inputs": [ {"documentUrl":"<public_ur_or_data_url>"} ], "callbackUrl": "<your_callback_url>"}'

In this example, the callbackUrl will be called with a POST request containing the job results when the job is completed.

Security Features

Static IP

To ensure secure communication between super.AI and customer systems, super.AI provides a static IP range that customers can trust. Customers can whitelist this IP in their firewalls to allow incoming traffic from superAI. The IP range will be shared with customers upon request.

ECDSA request body validation

When we send a request to a customer’s system we can include an encrypted header so that the customers can validate it agains the request body. The public key for the validation will be shared with customers upon request.

Verify Incoming Requests

To verify the signature of incoming webhook requests, follow these steps in your application code:

Extract the X-SuperAI-Webhook-Signature header from the incoming request.
Retrieve the raw request payload.
Use the public verification key provided by superAI to verify the signature of the request using the ECDSA algorithm.

Python Example

Here's an example in Python using the ecdsa library:

import base64
from hashlib import sha256
import ecdsa
from ecdsa.util import sigdecode_string

def verify_signature(request, public_key_pem):
    signature = request.headers.get("X-SuperAI-Webhook-Signature")
    payload: bytes = bytes.fromhex(request.content)

    with open(public_key_pem) as f:
      public_key = VerifyingKey.from_pem(f.read())

    return public_key.verify(payload, request.json(), sha256, sigdecode=sigdecode_string)

Replace request with the incoming webhook request and pub_key.pem with the public verification key obtained from superAI. This function will return True if the signature is valid, or False if the signature is invalid or missing.

Secure Webhooks using ECDSA Cryptographic Signing

This guide will help you secure superAI webhooks by verifying that incoming requests originate from superAI using Elliptic Curve Digital Signature Algorithm (ECDSA) cryptographic signing. This method allows you to ensure that the data you receive is from a trusted source.

Overview

When using ECDSA cryptographic signing, superAI will generate a private and public key pair. The private key will be used to generate a signature that is posted to your HTTP webhook in the X-SuperAI-Webhook-Signature header. You can verify the signature with the public key provided.

Obtain the Public Verification Key

Upon request, super.AI will provide you with the public verification key associated with your account. This key is used to verify incoming webhook requests signed with the corresponding private key.

Verify Incoming Requests

To verify the signature of incoming webhook requests, follow these steps in your application code:

Extract the X-SuperAI-Webhook-Signature header from the incoming request.
Retrieve the raw request payload.
Use the public verification key provided by super.AI to verify the signature of the request using the ECDSA algorithm.

Python Example

Here's an example in Python using the ecdsa library:

import base64
from hashlib import sha256
import ecdsa
from ecdsa.util import sigdecode_string

def verify_signature(request, public_key_pem):
    signature = request.headers.get("X-SuperAI-Webhook-Signature")
    payload: bytes = request.content

    public_key = ecdsa.VerifyingKey.from_pem(public_key_pem.encode())
    signature = base64.b64decode(signature)

    return public_key.verify(signature, payload, sha256, sigdecode=sigdecode_string)

Replace request with the incoming webhook request and public_key_pem with the public verification key obtained from superAI. This function will return True if the signature is valid, or False if the signature is invalid or missing.