Register Webhook

Register a new webhook endpoint for receiving event notifications.

Webhook Events: Available events to subscribe to:

• memory_processing_started: Triggered when memory processing begins
• memory_completed: Triggered when memory processing completes successfully
• memory_failed: Triggered when memory processing fails

Webhook Delivery Headers: All webhook delivery requests include:

• Content-Type: application/json
• User-Agent: NeoCore-Webhook/1.0
• X-NeoSapien-Event: <event_type> — The event type that triggered this delivery
• X-NeoSapien-Delivery: <uuid> — Unique delivery identifier

When secret_token is configured (always provided at registration), these additional headers are included:

• X-NeoSapien-Signature: sha256=<HMAC-SHA256 hex digest> — HMAC-SHA256 signature of {timestamp}.{payload}
• X-NeoSapien-Timestamp: <unix_timestamp> — Unix timestamp of when the signature was generated

Signature Verification (HMAC-SHA256): To verify the authenticity and integrity of a webhook delivery:

1. Extract the X-NeoSapien-Timestamp and X-NeoSapien-Signature headers
2. Construct the signature payload: {timestamp}.{raw_request_body}
3. Compute HMAC-SHA256 using your secret_token as the key
4. Compare with the signature from the header using a constant-time comparison
5. Optionally reject requests where the timestamp is older than 5 minutes (replay protection)

Example (Python):

import hmac, hashlib
expected = hmac.new(secret_token.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256).hexdigest()
is_valid = hmac.compare_digest(f"sha256={expected}", signature_header)

Request Requirements:

• webhook_url: Valid HTTPS URL endpoint to receive webhooks
• events: Array of event types to subscribe to (minimum 1)
• description: Optional description for webhook identification

Response Data:

• webhook_id: Unique identifier for the registered webhook
• secret_token: Secret token for HMAC signature verification (store securely — returned only once)
• webhook_url: Confirmed webhook URL
• events: Subscribed event types
• status: Webhook status (active by default)
• created_at: Registration timestamp

Error Handling:

• 400: Invalid URL format, empty events list, or validation errors
• 409: Webhook URL already registered for this account
• 500: Internal server error with detailed error information

Use Cases:

• Real-time notifications for memory processing events
• Integration with external systems and workflows
• Automated triggers for downstream processing
• Event-driven architecture implementation