API
Webhooks Getting Started
Learn how outbound Asiyst webhooks deliver signed real-time notifications to your website backend.
Overview & Definitions
Asiyst supports secure, enterprise-grade Outbound Webhooks to notify your external servers (such as an e-commerce platform or custom Next.js backend) whenever critical events happen in your project.
Webhook
A configured destination where Asiyst sends an HTTP POST request with a signed JSON payload whenever an event occurs. Example destination: https://caszio.com/api/asiyst/webhooks.
API Endpoint
An API route exposed by Asiyst that developer applications call (such as GET /api/v1/projects) or an endpoint hosted on your application to receive webhooks or interact with Asiyst.
Architecture Rule: Asiyst owns event generation and signature creation. Developers configure destinations and implement receiving endpoints. Developers cannot execute arbitrary server-side code within Asiyst.
Lifecycle of a Webhook Delivery
- Event Occurs: An action triggers an event in Asiyst (e.g. SDK verified, payment received, assistant answer completed).
- Eligibility Validation: The backend validates project isolation and event eligibility.
- Transactional Persistence: The event and delivery record are committed durably in the outbox.
- Subscription Matching: Active webhook subscriptions for the project are matched.
- HMAC-SHA256 Signing: An isolated worker signs the exact raw JSON body with the destination's secret.
- Outbound Dispatch: An HTTPS POST request is made with headers
X-Asiyst-TimestampandX-Asiyst-Signature.
- Response Logging: Latency, HTTP status code, and sanitized response excerpts are audited in delivery logs.
- Automated Retries: 429 and 5xx responses trigger exponential backoff retries.
Prerequisites
- An active Asiyst project.
- A publicly accessible HTTPS receiver URL (localhost and internal IP addresses are blocked to prevent SSRF).
- Access to the Asiyst Developer Console to configure destinations and copy signing secrets.