Webhooks

Overview

The Webhooks module lets your application subscribe to domain events emitted by SynthesQ and receive them in near-real-time. It supports two complementary delivery models:

• Push (Outbound Webhooks) - SynthesQ sends an HTTP POST to your endpoint whenever a subscribed event occurs. Each delivery includes an HMAC signature so you can verify authenticity.
• Pull (Event Feed) - A cursor-based API endpoint that stores recent events for on-demand polling. Use this as a fallback when push delivery is impractical or as a primary integration strategy for batch-oriented consumers.

Both models share the same event schema. You can use push delivery for low-latency workflows and the event feed for reconciliation, auditing, or catch-up after downtime.

Supported Event Types

Event Type	Entity	Description
product.created	Product	A new product was created
product.price_changed	Product	Product selling or cost price changed
product.activated	Product	Product was activated
product.deactivated	Product	Product was deactivated
product.discontinued	Product	Product was discontinued
customer.created	Customer	A new customer was created
customer.status_changed	Customer	Customer status was updated
customer.assigned	Customer	Customer was assigned to a new representative

Expanding Event Coverage

Additional modules can register their own events with the webhook system. The event types listed above reflect the current production configuration. As new modules are onboarded, their events will appear here.

Wildcard Subscriptions

You can subscribe to all events for an entity using a wildcard pattern such as product.* or customer.*. Use * to subscribe to every event type. See Managing Subscriptions for details on event patterns.

Quick Start

1. Create a subscription - call POST /api/v1/webhooks/subscriptions with your endpoint URL, a list of event patterns, and an optional secret. The response includes a generated signing secret if you did not supply one.

2. Receive events - SynthesQ sends an HTTP POST to your endpoint for each matching event. The payload includes the event type, entity data, and a timestamp. An HMAC signature is included in the X-Webhook-Signature header.

3. Verify signatures - use the shared secret to compute an HMAC-SHA256 of the raw request body and compare it to the signature header. This ensures the payload was sent by SynthesQ and has not been tampered with. See Managing Subscriptions for implementation examples.

Payload Data & Privacy

Webhook payloads are an external projection of the entity, not the full internal API representation. Fields classified as confidential or restricted — personal contact details (email, phone, address), compensation, commercial figures (lifetime value, cost, margin), free-text notes, and credential secrets — are omitted from outbound webhook payloads and from the event feed.

Identity, status, lifecycle dates, and relationship identifiers are always included, so you can react to an event and, if you need the redacted detail, fetch it from the authenticated REST API where your access is authorized.

Payload scope

The same entity is serialized more narrowly for webhooks than for the authenticated API. Do not rely on a webhook payload to carry a field you can see in the API response — confirm the field is present in the webhook contract. If a field you previously received stops appearing, it was reclassified as sensitive; retrieve it via the authenticated API instead.

Subscription Lifecycle

Status	Description	How to Transition
active	Receiving events and delivering to endpoint	Automatic on creation; or POST /{id}/activate
disabled	Not delivering events; can be re-enabled	POST /{id}/disable; automatic after sustained failures; reverse with POST /{id}/activate

Auto-Disable

Subscriptions are automatically disabled when the failure rate exceeds 95% over a 24-hour window with at least 10 delivery attempts. See Delivery & Reliability for the full auto-disable policy.

Configuration

Setting	Default	Description
retention_days	30	Number of days events are retained in the event feed
max_subscriptions	25	Maximum webhook subscriptions per tenant
max_retry_attempts	5	Maximum delivery attempts per event (including the initial attempt)
backoff_schedule	[0, 1, 5, 30, 120]	Retry delays in minutes between attempts
failure_threshold	95%	Failure rate that triggers auto-disable
failure_window	24 hours	Rolling window for failure rate calculation
min_deliveries_for_disable	10	Minimum deliveries in window before auto-disable can trigger

In This Section

• Managing Subscriptions - Create subscriptions, configure event patterns and payload modes, rotate secrets, and verify signatures.
• Event Feed - Poll for events using cursor-based pagination with filtering and retention policies.
• Delivery & Reliability - Understand the delivery lifecycle, retry strategy, auto-disable behaviour, and idempotency guarantees.