Webhooks
Webhooks deliver real-time event notifications to your server whenever something happens in MemorySync. Create endpoints, subscribe to events, and receive signed HTTP POST requests with event payloads — all managed through the organization-scoped webhook API.
How webhooks work
When an event occurs (e.g., a memory is created or an API key is rotated), MemorySync dispatches an HTTP POST to every subscribed endpoint. The dispatch system:
- Signs each request with HMAC so you can verify authenticity.
- Retries failed deliveries with exponential backoff.
- Tracks delivery status, latency, and response for every attempt.
- Supports per-endpoint configuration for retry policies, signature algorithms, and event filtering.
Endpoints are managed at /org/webhooks and are scoped to your organization. RBAC and scope checks are enforced before any mutation.
Available events
| Event | Triggered when |
|---|---|
memory.created | A new memory is stored. |
memory.updated | A memory's content or metadata changes. |
memory.deleted | A memory is soft-deleted or purged. |
memory.queried | A memory query is executed. |
team.member_added | A user is added to the organization. |
team.member_removed | A user is removed. |
api_key.created / api_key.revoked | An API key is created or revoked. |
billing.usage_threshold | Usage crosses a configured threshold. |
api.rate_limited | A request was rejected due to rate limiting. |
Creating an endpoint
Create a webhook endpoint by sending a POST to /org/webhooks. The request body accepts these fields:
| Field | Description |
|---|---|
name | Human-readable endpoint name. |
url | Destination URL. Must be http:// or https://. |
events | Array of event names to subscribe to. |
project_id | Optional. Scope deliveries to a specific project. |
description | Optional description. |
retry_config | Optional per-endpoint retry policy (see Retry section). |
signature_config | Optional per-endpoint signature settings (see Signature section). |
Signature verification
Every webhook delivery is signed so you can verify it came from MemorySync. The signature is computed as HMAC(secret, timestamp + "." + body) and sent in HTTP headers:
| Setting | Default |
|---|---|
| Algorithm | hmac-sha256 (also supports hmac-sha512) |
| Signature header | X-MemorySync-Signature |
| Timestamp header | X-MemorySync-Timestamp |
| Tolerance | 300 seconds (configurable, range: 60–3600) |
Reject any request where the timestamp is outside the tolerance window to prevent replay attacks.
Retry & backoff
When a delivery fails (non-2xx response or timeout), the system retries with exponential backoff. You can configure these settings per endpoint:
| Setting | Default / Range |
|---|---|
| Enabled | true |
| Max retries | 5 (range: 1–10) |
| Initial delay | 1 second (range: 1–60) |
| Max delay | 3600 seconds (range: 60–86400) |
| Backoff multiplier | 2.0 (range: 1.0–5.0) |
| Retry status codes | 408, 429, 500, 502, 503, 504 |
Delivery tracking
Every delivery attempt is recorded with detailed telemetry. You can inspect delivery history through the API or dashboard:
- Per delivery: event type, event ID, payload hash, signature, HTTP status code, response body, error message, latency in milliseconds, attempt number, and retry schedule.
- Per endpoint: total deliveries, successful deliveries, failed deliveries, consecutive failures, success rate, and last-triggered timestamps.
- Failed deliveries that exhaust all retries are moved to a dead-letter queue where you can manually retry them.
Health metrics
The health-metrics endpoint provides an organization-level overview of webhook health:
- Active webhooks — number of enabled endpoints.
- Delivery counts — total, successful, and failed deliveries across all endpoints.
- Success rate — percentage of deliveries that received a 2xx response.
- Failing endpoints — endpoints with consecutive failures above the threshold.
- Pending retries — deliveries scheduled for retry.
- Dead-letter count — deliveries that exhausted all retries and need manual attention.