---
title: "Register Webhook"
method: POST
path: "/api/v1/webhooks/register"
tags: ["Webhooks"]
---

# Register Webhook

`POST /api/v1/webhooks/register`

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):
```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

## Request body

- RegisterWebhookRequest — Request model for registering a webhook
  - `webhook_url` string, uri, required — The URL to send webhook events to
  - `events` string[], required — List of events to subscribe to
  - `description` string, nullable — Optional description of the webhook

## Response `201`

Webhook registered successfully with secret token

- WebhookRegisterSuccessResponse — Webhook registration success response (HTTP 201)
  - `success` boolean — Operation success status - always true for 201 responses
  - `data` WebhookData, required — Webhook data structure for API responses
    - `webhook_id` string, required — Unique webhook identifier
    - `webhook_url` string, required — The URL to send webhook events to
    - `secret_token` string, required — Secret token for webhook signature verification
    - `events` string[], required — List of subscribed events
    - `status` string, required — Webhook status
    - `created_at` string, date-time, required — Webhook creation timestamp
    - `description` string, nullable — Optional description of the webhook
  - `error` unknown
  - `meta` MetaData, required — Response metadata structure
    - `timestamp` string, required — Response timestamp
    - `request_id` string, required — Request ID
    - `api_version` string, required — API version
    - `execution_time_ms` integer, required — Execution time in milliseconds

## Other responses

- `400` — Invalid webhook data
- `409` — Webhook URL already exists
- `422` — Validation Error
- `500` — Internal server error

---

[API](https://skmtc.dev/neosapien/apis/neocore.md) · [All operations](https://skmtc.dev/neosapien/apis/neocore/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/neosapien/neocore/revisions/8b94ef58f2cf/schema)