Webhooks

Setup

Configure webhooks in the Dashboard or via the API. Each webhook endpoint receives events as HTTP POST requests with a JSON body.

Provide an HTTPS URL that can receive POST requests. The URL must return a 2xx status code within 30 seconds.

Select event types

Choose which event types to subscribe to. You can subscribe to all events or specific types.

Store your signing secret

Synap generates an HMAC signing secret for your endpoint. Store it securely — you will need it to verify webhook signatures.

Verify signatures in your handler

Every webhook request includes a signature header. Verify it before processing the payload.

Signature Verification

Every webhook request includes an X-Synap-Signature header containing an HMAC-SHA256 signature of the request body. Always verify this signature to ensure the request is authentic. The signature is computed as:

HMAC-SHA256(signing_secret, raw_request_body)

Verification Examples

import hmac
import hashlib

def verify_webhook(request_body: bytes, signature: str, signing_secret: str) -> bool:
    expected = hmac.new(
        signing_secret.encode("utf-8"),
        request_body,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
# body = await request.body()
# signature = request.headers["X-Synap-Signature"]
# if not verify_webhook(body, signature, SIGNING_SECRET):
#     return Response(status_code=401)

Always use constant-time comparison (e.g., hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js) to prevent timing attacks when verifying signatures.

Delivery Behavior

Retry Policy

If your endpoint returns a non-2xx status code or does not respond within 30 seconds, Synap retries delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed attempts, the event is marked as failed and no further retries are attempted. Failed events are visible in the Dashboard webhook logs for 30 days.

Delivery Statuses

Status	Description
`pending`	Event is queued for delivery
`delivered`	Endpoint returned a 2xx response
`retrying`	Delivery failed, retrying with backoff
`failed`	All retry attempts exhausted

Ordering

Webhook events are delivered in approximate chronological order but not guaranteed to be strictly ordered. Use the timestamp field in the payload to determine the actual event sequence.

Idempotency

Each event has a unique event_id. Your handler should be idempotent — the same event may be delivered more than once in rare cases (e.g., network timeouts where the response was lost).

Common Headers

Every webhook request includes these headers:

Header	Description
`Content-Type`	Always `application/json`
`X-Synap-Signature`	HMAC-SHA256 signature of the request body
`X-Synap-Event`	The event type (e.g., `conversation.started`)
`X-Synap-Delivery-Id`	Unique delivery attempt ID
`X-Synap-Timestamp`	ISO 8601 timestamp of when the event was sent
`User-Agent`	`Synap-Webhooks/1.0`

Event Types

conversation.started

Fired when a new conversation is initiated with the SDK.

{
  "event_id": "evt_1a2b3c4d5e6f7890",
  "event_type": "conversation.started",
  "timestamp": "2025-01-15T10:00:00Z",
  "instance_id": "inst_f1e2d3c4b5a69078",
  "data": {
    "conversation_id": "conv_abc123",
    "user_id": "user_789",
    "customer_id": "cust_456",
    "metadata": {
      "source": "web-chat",
      "session_id": "sess_xyz"
    },
    "started_at": "2025-01-15T10:00:00Z"
  }
}

Show Payload fields

event_id

string

Unique event identifier for idempotency.

event_type

string

Always conversation.started.

timestamp

string

ISO 8601 timestamp of the event.

instance_id

string

The instance where the conversation was started.

data.conversation_id

string

The new conversation identifier.

data.user_id

string

The user who started the conversation. May be null for anonymous conversations.

data.customer_id

string

The customer scope for this conversation. May be null.

data.metadata

object

Metadata attached to the conversation.

data.started_at

string

ISO 8601 timestamp of when the conversation began.

conversation.ended

Fired when a conversation is explicitly ended or times out.

{
  "event_id": "evt_2b3c4d5e6f7a8901",
  "event_type": "conversation.ended",
  "timestamp": "2025-01-15T11:30:00Z",
  "instance_id": "inst_f1e2d3c4b5a69078",
  "data": {
    "conversation_id": "conv_abc123",
    "user_id": "user_789",
    "customer_id": "cust_456",
    "reason": "user_ended",
    "duration_seconds": 5400,
    "message_count": 24,
    "memories_created": 7,
    "ended_at": "2025-01-15T11:30:00Z"
  }
}

Show Payload fields

data.reason

string

Why the conversation ended. One of: user_ended, timeout, agent_ended, error.

data.duration_seconds

integer

Total conversation duration in seconds.

data.message_count

integer

Total number of messages in the conversation.

data.memories_created

integer

Number of memories extracted and stored from this conversation.

data.ended_at

string

ISO 8601 timestamp of when the conversation ended.

context.retrieved

Fired when context is fetched for a conversation.

{
  "event_id": "evt_3c4d5e6f7a8b9012",
  "event_type": "context.retrieved",
  "timestamp": "2025-01-15T10:05:00Z",
  "instance_id": "inst_f1e2d3c4b5a69078",
  "data": {
    "conversation_id": "conv_abc123",
    "user_id": "user_789",
    "mode": "balanced",
    "results_count": 5,
    "query_time_ms": 47,
    "tokens_used": 312,
    "memory_types_returned": ["fact", "preference"],
    "search_queries": ["coffee preferences", "location"]
  }
}

Show Payload fields

data.mode

string

Retrieval mode used: fast, balanced, or accurate.

data.results_count

integer

Number of memory items returned.

data.query_time_ms

integer

Total query execution time in milliseconds.

data.tokens_used

integer

Total tokens consumed by the context response.

data.memory_types_returned

string[]

Which memory types were included in the response.

data.search_queries

string[]

The search queries used for retrieval.

config.applied

Fired when a memory architecture configuration is applied to an instance.

{
  "event_id": "evt_4d5e6f7a8b9c0123",
  "event_type": "config.applied",
  "timestamp": "2025-01-15T17:00:00Z",
  "instance_id": "inst_f1e2d3c4b5a69078",
  "data": {
    "config_id": "maca_cfg_5e6f7a8b",
    "version": 2,
    "applied_by": "user_admin_001",
    "mode": "graceful",
    "previous_config_id": "maca_cfg_1a2b3c4d",
    "previous_version": 1,
    "changes_summary": {
      "retrieval.context_budget": {
        "from": 4096,
        "to": 8192
      },
      "retrieval.mode": {
        "from": "balanced",
        "to": "accurate"
      }
    },
    "applied_at": "2025-01-15T17:00:00Z"
  }
}

Show Payload fields

data.config_id

string

The configuration version that was applied.

data.version

integer

Sequential version number.

data.applied_by

string

User ID of the person who applied the configuration.

data.mode

string

Application mode: immediate, graceful, or canary.

data.previous_config_id

string

The config ID that was replaced. null for the first configuration.

data.changes_summary

object

A diff of the changed fields, showing from and to values for each modified setting.

data.applied_at

string

ISO 8601 timestamp of when the config became active.

compaction.completed

Fired when a context compaction completes successfully.

{
  "event_id": "evt_5e6f7a8b9c0d1234",
  "event_type": "compaction.completed",
  "timestamp": "2025-01-15T16:00:05Z",
  "instance_id": "inst_f1e2d3c4b5a69078",
  "data": {
    "compaction_id": "cmp_1a2b3c4d5e6f7890",
    "conversation_id": "conv_abc123",
    "user_id": "user_789",
    "strategy": "summarize",
    "version": 1,
    "tokens_before": 2847,
    "tokens_after": 487,
    "compression_ratio": 5.8,
    "validation_score": 0.94,
    "processing_time_ms": 3200,
    "completed_at": "2025-01-15T16:00:05Z"
  }
}

Show Payload fields

data.compaction_id

string

Unique compaction identifier.

data.conversation_id

string

The conversation that was compacted.

data.strategy

string

Compaction strategy used: summarize, extract, hierarchical, or temporal.

data.version

integer

Compaction version number for this conversation.

data.tokens_before

integer

Token count before compaction.

data.tokens_after

integer

Token count after compaction.

data.compression_ratio

number

Achieved compression ratio.

data.validation_score

number

Quality score between 0.0 and 1.0 measuring information preservation.

data.processing_time_ms

integer

Time taken to perform the compaction in milliseconds.

Testing Webhooks

Dashboard
CLI
Local Development

Use the Dashboard webhook testing tool to send test events to your endpoint. Navigate to Settings > Webhooks > Test and select an event type.

Use the Synap CLI to trigger test webhook events:

synap webhooks test \
  --endpoint-id whep_abc123 \
  --event-type conversation.started

For local development, use a tool like ngrok to expose your local server:

# Terminal 1: Start your webhook handler
python webhook_handler.py  # listening on port 8000

# Terminal 2: Expose it publicly
ngrok http 8000
# Use the ngrok HTTPS URL as your webhook endpoint

Best Practices

Respond quickly

Return a 2xx response as soon as possible. Process the webhook payload asynchronously in a background job rather than doing heavy work in the handler.

Handle duplicates

Use the event_id to deduplicate events. Store processed event IDs and skip any you have already handled.

Verify signatures

Always verify the X-Synap-Signature header. Reject requests with invalid signatures to prevent spoofing.

Use HTTPS

Webhook endpoints must use HTTPS. Synap does not deliver events to plaintext HTTP endpoints.

Getting Started

Concepts

Setup & Integration

SDK

Dashboard

Connectors

Migration

Guides

Resources

Setup

Signature Verification

Verification Examples

Delivery Behavior

Retry Policy

Delivery Statuses

Ordering

Idempotency

Common Headers

Event Types

conversation.started

conversation.ended

context.retrieved

config.applied

compaction.completed

Testing Webhooks

Best Practices

Respond quickly

Handle duplicates

Verify signatures

Use HTTPS

Getting Started

Concepts

Setup & Integration

SDK

Dashboard

Connectors

Migration

Guides

Resources

​Setup

​Signature Verification

​Verification Examples

​Delivery Behavior

​Retry Policy

​Delivery Statuses

​Ordering

​Idempotency

​Common Headers

​Event Types

​conversation.started

​conversation.ended

​context.retrieved

​config.applied

​compaction.completed

​Testing Webhooks

​Best Practices

Respond quickly

Handle duplicates

Verify signatures

Use HTTPS

Setup

Signature Verification

Verification Examples

Delivery Behavior

Retry Policy

Delivery Statuses

Ordering

Idempotency

Common Headers

Event Types

conversation.started

conversation.ended

context.retrieved

config.applied

compaction.completed

Testing Webhooks

Best Practices