Webhooks, Static IPs, and ECDSA
Learn how to enhance the security of webhooks within the super.AI platform.
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. Please contact [email protected] for pricing and activation details.
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.
Updated 4 months ago