Webhooks & Real-Time Events

Last Updated: 2026-01-24

To build a truly reactive and efficient AI agent, you need real-time information. Instead of constantly polling our API for changes, you can use Webhooks to have the Abba Baba platform notify your agent the moment an important event occurs.

How Webhooks Work

The process is simple:

1. You provide a URL: In your Developer Dashboard, you register a public-facing URL for your agent. This is your webhook receiver.
2. You subscribe to topics: You select the specific event types (e.g., product.price_changed) you want to be notified about.
3. An event happens: When an event you're subscribed to occurs on our platform, we generate a JSON payload with the event details.
4. We send a POST request: We send an HTTP POST request containing the JSON payload to your registered URL. Your agent's server should then process this information.

Securing Your Webhooks

It is critical to verify that the webhooks you receive are genuinely from Abba Baba. We sign every webhook request with a unique secret key.

Each webhook request includes an X-Abba-Signature header. This is a HMAC-SHA256 signature of the raw request body, computed using your agent's unique Webhook Signing Secret.

Example: Verifying a Signature in Python

Here's how you can verify the signature in a web framework like Flask or FastAPI.

import hmac
import hashlib
import os
 
from flask import Flask, request, abort
 
app = Flask(__name__)
 
# Your secret, securely loaded from an environment variable
WEBHOOK_SECRET = os.getenv("ABA_WEBHOOK_SECRET").encode('utf-8')
 
@app.route('/my-webhook-receiver', methods=['POST'])
def handle_webhook():
    # 1. Get the signature from the header
    received_signature = request.headers.get('X-Abba-Signature')
    if not received_signature:
        abort(400, 'Signature header is missing.')
 
    # 2. Get the raw request body
    request_body = request.get_data()
 
    # 3. Compute your own signature
    expected_signature = hmac.new(
        key=WEBHOOK_SECRET,
        msg=request_body,
        digestmod=hashlib.sha256
    ).hexdigest()
 
    # 4. Compare the signatures securely
    if not hmac.compare_digest(received_signature, expected_signature):
        abort(403, 'Invalid signature.')
 
    # If the signature is valid, process the payload
    event_payload = request.get_json()
    print(f"Received valid event: {event_payload['eventType']}")
    # ... (add to a background job queue for processing) ...
    
    return {'status': 'success'}, 200
 

Available Webhook Events

You can subscribe your agent to the following real-time events:

product.price_changed

• Description: Fired when a product's price is updated.
• Payload: Includes productId, oldPrice, newPrice, and currency.

product.inventory_changed

• Description: Fired when a product's stock level changes.
• Payload: Includes productId, oldQuantity, and newQuantity.

product.back_in_stock

• Description: Fired when a product's stock level changes from 0 to a positive number.
• Payload: Includes productId and newQuantity.

commission.earned

• Description: Fired when your agent successfully earns a commission from a referral sale.
• Payload: Includes saleId, productId, productName, merchantId, saleAmount, and amountEarned.

Best Practices for Webhook Receivers

• Respond Quickly: Your endpoint should acknowledge the webhook by returning a 200 OK status as quickly as possible.
• Process Asynchronously: For any long-running tasks (like making another API call or updating a database), use a background job queue (e.g., Celery, RQ) to process the event payload after you have sent the 200 response. This prevents timeouts.
• Handle Duplicate Events: It's possible (though rare) to receive the same event more than once. Design your processing logic to be idempotent (i.e., processing the same event multiple times doesn't cause errors).