Webhooks
Receive real-time notifications when events happen in your Hebbrix account. Webhooks let you build reactive integrations that respond instantly to memory changes, document processing, and more.
How Webhooks Work
When an event occurs (like a new memory being created), Hebbrix sends an HTTP POST request to your configured endpoint with details about the event. Your server processes the payload and responds with a 2xx status to acknowledge receipt.
Event Occurs
Memory created, document processed, etc.
Webhook Fired
POST request sent to your endpoint
You Process
Handle the event and respond 2xx
Supported Events
| Event | Description |
|---|---|
memory.created | A new memory was created |
memory.updated | A memory was updated |
memory.deleted | A memory was deleted |
document.processing | Document processing started |
document.completed | Document processing finished |
document.failed | Document processing failed |
collection.created | A new collection was created |
collection.deleted | A collection was deleted |
profile.updated | User profile was updated |
entity.discovered | New entity added to knowledge graph |
Endpoints
Webhook Payload
Every webhook delivery includes these standard fields:
{
"id": "evt_abc123xyz",
"type": "memory.created",
"created_at": "2024-01-15T10:30:00Z",
"data": {
"id": "mem_xyz789",
"content": "User prefers dark mode",
"collection_id": "col_default",
"importance": 0.75,
"created_at": "2024-01-15T10:30:00Z"
},
"webhook_id": "wh_abc123",
"attempt": 1
}Verifying Signatures
Always verify signatures
Every webhook includes a signature in the X-Hebbrix-Signature header. Verify this to ensure the request came from Hebbrix.
import hmac
import hashlib
from flask import Flask, request
app = Flask(__name__)
WEBHOOK_SECRET = "whsec_your_secret_here"
@app.route("/webhooks/hebbrix", methods=["POST"])
def handle_webhook():
# Get the signature from headers
signature = request.headers.get("X-Hebbrix-Signature")
timestamp = request.headers.get("X-Hebbrix-Timestamp")
# Create the signed payload
payload = f"{timestamp}.{request.data.decode()}"
# Calculate expected signature
expected = hmac.new(
WEBHOOK_SECRET.encode(),
payload.encode(),
hashlib.sha256
).hexdigest()
# Verify signature matches
if not hmac.compare_digest(signature, f"sha256={expected}"):
return "Invalid signature", 401
# Process the event
event = request.json
print(f"Received event: {event['type']}")
if event["type"] == "memory.created":
handle_memory_created(event["data"])
elif event["type"] == "document.completed":
handle_document_completed(event["data"])
return "OK", 200import crypto from 'crypto';
import express from 'express';
const app = express();
const WEBHOOK_SECRET = 'whsec_your_secret_here';
app.post('/webhooks/hebbrix', express.raw({type: 'application/json'}), (req, res) => {
const signature = req.headers['x-hebbrix-signature'];
const timestamp = req.headers['x-hebbrix-timestamp'];
// Create the signed payload
const payload = `${timestamp}.${req.body.toString()}`;
// Calculate expected signature
const expected = `sha256=${crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(payload)
.digest('hex')}`;
// Verify signature matches
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
return res.status(401).send('Invalid signature');
}
// Process the event
const event = JSON.parse(req.body.toString());
console.log(`Received event: ${event.type}`);
switch (event.type) {
case 'memory.created':
handleMemoryCreated(event.data);
break;
case 'document.completed':
handleDocumentCompleted(event.data);
break;
}
res.status(200).send('OK');
});Retry Policy
If your endpoint doesn't respond with a 2xx status, we'll retry with exponential backoff:
After 4 failed attempts, the webhook is marked as failed. You can view failed deliveries in the dashboard and manually retry them.
Best Practices
Respond Quickly
Return a 2xx response within 30 seconds. Process events asynchronously if needed.
Handle Duplicates
Use the event ID to deduplicate. The same event may be delivered multiple times.
Verify Signatures
Always verify the X-Hebbrix-Signature header to ensure authenticity.
Use HTTPS
Webhook endpoints must use HTTPS for security. HTTP endpoints are rejected.
cURL Example
/v1/webhookscurl -X POST "https://api.hebbrix.com/v1/webhooks" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/hebbrix",
"events": [
"memory.created",
"document.completed"
]
}'