Webhooks

Subscribe an endpoint

1. Open Settings → Developer tools → Webhooks in the workspace.
2. Select New endpoint and enter a public HTTPS URL your application controls.
3. Optionally add a description and select event topics. Leave all topics clear to receive every event.
4. Create the endpoint and store its whsec_... signing secret while it is shown.
5. Use Send test event on its row to confirm your receiver accepts a signed request.

Each endpoint belongs to one workspace. Topics include contact and opportunity changes, form submissions, appointment changes, received messages, social post results, and payment results. The current topic list is in the endpoint dialog. These are outbound Systemly events, separate from the provider webhooks used by Stripe, Twilio, or social connections.

Read the delivery

Systemly POSTs JSON containing topic, workspaceId, optional contactId, occurredAt, anddata. A test delivery also has test: true. The headers include the event topic, a stable delivery ID, a Unix-seconds timestamp, and a versioned signature:

X-Systemly-Topic: contact.created
X-Systemly-Delivery: <delivery-id>
X-Systemly-Timestamp: <unix-seconds>
X-Systemly-Signature: v1=<hex-hmac-sha256>

Reply with a 2xx status after accepting the event. Use the delivery ID as a deduplication key because the same event may be retried. Keep your receiver fast; the delivery attempt times out after 10 seconds.

Verify before processing

Compute HMAC-SHA256 with the endpoint secret over the exact string<timestamp>.<raw request body>. Compare the result with the hex digest after v1= using a constant-time comparison. Use the raw bytes before JSON parsing or reformatting, and reject stale timestamps to limit replay attempts. The Developers Reference tab has a minimal verification example.

Retries and endpoint controls

• A 2xx response marks a delivery successful. Non-2xx responses and transient network errors can be retried, up to five attempts.
• Pending failed attempts are retried by the maintenance process while the delivery is less than 24 hours old. A blocked or unsafe destination fails without retrying.
• The endpoint switch pauses future delivery; Delete stops it and removes the endpoint.
• The row shows a delivery count. Use Send test event after changing your receiver or DNS.