{"title":"Webhooks","slug":"webhooks","category":"api","summary":"","audience":["human"],"tags":[],"word_count":562,"read_minutes":3,"llm_context":"Webhook management via REST API. Create, list, get, delete, enable/disable and test webhooks. Events: memory.created, memory.updated, memory.deleted, memory.verified, memory.unverified, task.updated, chat.message_sent. Webhooks fire HTTP POST to configured URL with HMAC-SHA256 signature.","lang":"en","translated":true,"requested_lang":"en","content_markdown":"# Webhooks\n\n## Overview\n\nWebhooks allow you to receive HTTP callbacks when events occur in your Synapse mind. When an event triggers, Synapse sends a `POST` request to the URL you configured, with a JSON body containing event data and a HMAC-SHA256 signature for verification.\n\nWebhooks have a **20 webhooks per mind** limit.\n\n## Events\n\n| Event | Description |\n|-------|-------------|\n| `memory.created` | Fired when a new memory is stored |\n| `memory.updated` | Fired when a memory is updated |\n| `memory.deleted` | Fired when a memory is deleted |\n| `memory.verified` | Fired when a memory is verified |\n| `memory.unverified` | Fired when a memory is unverified |\n| `task.updated` | Fired when a scheduled task status changes |\n| `chat.message_sent` | Fired when a chat message is sent |\n\n## Create Webhook\n\n`POST /webhooks`\n\nCreate a new webhook for the authenticated mind.\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `url` | string | yes | The URL to call when the event fires. Must be HTTPS (or `http://localhost` for development). |\n| `events` | string | yes | Comma-separated event patterns. Use `*` for all events. Examples: `memory.*`, `chat.*` |\n| `secret` | string | yes | Secret for HMAC-SHA256 signature verification. |\n\n### Response\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string (UUID) | Webhook ID |\n| `url` | string | Webhook URL |\n| `events` | string | Event pattern (e.g. `memory.*`) |\n| `mind_id` | string (UUID) | Mind that owns this webhook |\n| `enabled` | boolean | Whether the webhook is enabled |\n| `created_at` | number | Unix timestamp (seconds) |\n\n## List Webhooks\n\n`GET /webhooks`\n\nLists all webhooks for the authenticated mind.\n\n### Response\n\nArray of webhook objects with the following fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `id` | string (UUID) | Webhook ID |\n| `url` | string | Webhook URL |\n| `events` | string | Event pattern (e.g. `memory.*`) |\n| `mind_id` | string (UUID) | Mind that owns this webhook |\n| `enabled` | boolean | Whether the webhook is enabled |\n| `created_at` | number | Unix timestamp (seconds) |\n| `last_call` | number or null | Unix timestamp of last call |\n| `last_status` | number or null | HTTP status code of last call |\n| `last_error` | string or null | Error message from last call |\n\n## Get Webhook\n\n`GET /webhooks/:id`\n\nGets a single webhook by ID. Requires ownership.\n\n### Response\n\nSame fields as List.\n\n## Update Webhook\n\n`PUT /webhooks/:id`\n\nUpdate a webhook's URL, events, or secret. Requires ownership.\n\n### Request Body\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `url` | string | no | New webhook URL |\n| `events` | string | no | New event patterns |\n| `secret` | string | no | New secret |\n\n## Enable / Disable Webhook\n\n`POST /webhooks/:id/enable`\n\nEnable a webhook. Requires ownership.\n\n`POST /webhooks/:id/disable`\n\nDisable a webhook. Requires ownership.\n\n## Test Webhook\n\n`POST /webhooks/:id/test`\n\nSends a test event (`memory.created`) to the webhook URL. Requires ownership.\n\n## Delete Webhook\n\n`DELETE /webhooks/:id`\n\nDelete a webhook by ID. Requires ownership.\n\n## Example\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/webhooks \\\n -H \"Authorization: Bearer YOUR_MIND_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"url\": \"https://example.com/webhook\",\n \"events\": \"memory.*\",\n \"secret\": \"your-webhook-secret\"\n}'\n```\n\n### Response\n\n```json\n{\n \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n \"url\": \"https://example.com/webhook\",\n \"events\": \"memory.*\",\n \"mind_id\": \"a1b2c3d4-e5f6-7890-abcd-ef1234567890\",\n \"enabled\": true,\n \"created_at\": 1782756632\n}\n```\n\n## Signature Verification\n\nThe webhook payload includes an HMAC-SHA256 signature in the `X-Synapse-Signature` header. **The signature is computed over the raw request body bytes** (not parsed-then-restringified JSON).\n\n```python\nimport hashlib, hmac\n\n# IMPORTANT: Use the RAW request body bytes, not parsed JSON\npayload_body = request.get_data() # Flask; or request.body in Django/FastAPI\n\nsig = hmac.new(\n webhook_secret.encode(),\n payload_body,\n hashlib.sha256\n).hexdigest()\n\nexpected_header = f\"sha256={sig}\"\nactual_header = request.headers.get('X-Synapse-Signature', '')\nassert hmac.compare_digest(expected_header, actual_header)\n```\n\n## Limits & Auto-Disable\n\n- **Rate Limit**: 20 webhooks per mind.\n- **Auto-Disable**: A webhook returning HTTP 410 (Gone) is automatically disabled. This allows remote services to signal \"stop sending\" without deleting the webhook configuration.\n\n## Deprecated Event Names\n\n| Old Name | New Name |\n|----------|----------|\n| `memory.store` | `memory.created` |\n| `memory.update` | `memory.updated` |\n| `memory.delete` | `memory.deleted` |\n","content_html":"

Webhooks

\n

Overview

\n

Webhooks allow you to receive HTTP callbacks when events occur in your Synapse mind. When an event triggers, Synapse sends a POST request to the URL you configured, with a JSON body containing event data and a HMAC-SHA256 signature for verification.

\n

Webhooks have a 20 webhooks per mind limit.

\n

Events

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
EventDescription
memory.createdFired when a new memory is stored
memory.updatedFired when a memory is updated
memory.deletedFired when a memory is deleted
memory.verifiedFired when a memory is verified
memory.unverifiedFired when a memory is unverified
task.updatedFired when a scheduled task status changes
chat.message_sentFired when a chat message is sent
\n

Create Webhook

\n

POST /webhooks

\n

Create a new webhook for the authenticated mind.

\n

Request Body

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
urlstringyesThe URL to call when the event fires. Must be HTTPS (or http://localhost for development).
eventsstringyesComma-separated event patterns. Use * for all events. Examples: memory.*, chat.*
secretstringyesSecret for HMAC-SHA256 signature verification.
\n

Response

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
idstring (UUID)Webhook ID
urlstringWebhook URL
eventsstringEvent pattern (e.g. memory.*)
mind_idstring (UUID)Mind that owns this webhook
enabledbooleanWhether the webhook is enabled
created_atnumberUnix timestamp (seconds)
\n

List Webhooks

\n

GET /webhooks

\n

Lists all webhooks for the authenticated mind.

\n

Response

\n

Array of webhook objects with the following fields:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeDescription
idstring (UUID)Webhook ID
urlstringWebhook URL
eventsstringEvent pattern (e.g. memory.*)
mind_idstring (UUID)Mind that owns this webhook
enabledbooleanWhether the webhook is enabled
created_atnumberUnix timestamp (seconds)
last_callnumber or nullUnix timestamp of last call
last_statusnumber or nullHTTP status code of last call
last_errorstring or nullError message from last call
\n

Get Webhook

\n

GET /webhooks/:id

\n

Gets a single webhook by ID. Requires ownership.

\n

Response

\n

Same fields as List.

\n

Update Webhook

\n

PUT /webhooks/:id

\n

Update a webhook's URL, events, or secret. Requires ownership.

\n

Request Body

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
FieldTypeRequiredDescription
urlstringnoNew webhook URL
eventsstringnoNew event patterns
secretstringnoNew secret
\n

Enable / Disable Webhook

\n

POST /webhooks/:id/enable

\n

Enable a webhook. Requires ownership.

\n

POST /webhooks/:id/disable

\n

Disable a webhook. Requires ownership.

\n

Test Webhook

\n

POST /webhooks/:id/test

\n

Sends a test event (memory.created) to the webhook URL. Requires ownership.

\n

Delete Webhook

\n

DELETE /webhooks/:id

\n

Delete a webhook by ID. Requires ownership.

\n

Example

\n
curl -X POST https://synapse.schaefer.zone/webhooks \\\n  -H "Authorization: Bearer YOUR_MIND_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d '{\n  "url": "https://example.com/webhook",\n  "events": "memory.*",\n  "secret": "your-webhook-secret"\n}'

Response

\n
{\n  "id": "550e8400-e29b-41d4-a716-446655440000",\n  "url": "https://example.com/webhook",\n  "events": "memory.*",\n  "mind_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",\n  "enabled": true,\n  "created_at": 1782756632\n}

Signature Verification

\n

The webhook payload includes an HMAC-SHA256 signature in the X-Synapse-Signature header. The signature is computed over the raw request body bytes (not parsed-then-restringified JSON).

\n
import hashlib, hmac\n\n# IMPORTANT: Use the RAW request body bytes, not parsed JSON\npayload_body = request.get_data()  # Flask; or request.body in Django/FastAPI\n\nsig = hmac.new(\n    webhook_secret.encode(),\n    payload_body,\n    hashlib.sha256\n).hexdigest()\n\nexpected_header = f"sha256={sig}"\nactual_header = request.headers.get('X-Synapse-Signature', '')\nassert hmac.compare_digest(expected_header, actual_header)

Limits & Auto-Disable

\n\n

Deprecated Event Names

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Old NameNew Name
memory.storememory.created
memory.updatememory.updated
memory.deletememory.deleted
\n","urls":{"html":"/docs/api/webhooks","text":"/docs/api/webhooks?format=text","json":"/docs/api/webhooks?format=json","llm":"/docs/api/webhooks?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}