Webhook, Email & Notification API
Webhook subscriptions, email sending/bulk, message templates, and real-time notifications with SignalR.
The Webhook, Email & Notification API provides event-driven integrations, transactional email delivery, template management, and real-time in-app notifications. Webhooks use HMAC signature verification for security.
Webhooks
Webhooks allow external systems to subscribe to SCRIPE events. When an event occurs (admin created, user registered, etc.), SCRIPE sends an HTTP POST to the subscriber URL with a signed payload. Failed deliveries are retried up to 3 times with exponential backoff.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/webhooks | List all webhook subscriptions for the current tenant. | 🔒 Required |
| POST | /api/v1/webhooks | Create a new webhook subscription with URL, events, and HMAC secret. | 🔒 Required |
| PUT | /api/v1/webhooks/{id} | Update a webhook's URL, events, or active status. | 🔒 Required |
| DELETE | /api/v1/webhooks/{id} | Delete a webhook subscription. | 🔒 Required |
| POST | /api/v1/webhooks/{id}/test | Send a test event to the webhook URL to verify connectivity. | 🔒 Required |
POST /webhooks — RequestJSON
{
"url": "https://api.example.com/webhooks/scripe",
"secret": "whsec_a1b2c3d4e5f6...",
"events": [
"admin.created",
"admin.updated",
"admin.deleted",
"user.registered",
"tenant.settings_changed"
],
"isActive": true,
"description": "Sync admin changes to external system"
}| Event Type | Trigger | Data Fields |
|---|---|---|
| admin.created | New admin registered | adminId, email, role, tenantId |
| admin.updated | Admin profile changed | adminId, changedFields |
| admin.deleted | Admin soft-deleted | adminId, deletedBy |
| admin.blocked | Admin account blocked | adminId, blockedBy, reason |
| user.registered | New user registration | userId, email, tenantId |
| user.verified | Email/phone verified | userId, verificationType |
| tenant.created | New tenant created | tenantId, name, parentId |
| tenant.settings_changed | Tenant settings updated | tenantId, changedSettings |
| role.permissions_changed | Role permissions modified | roleId, addedPerms, removedPerms |
| Failed Login Attempt | Failed login attempt | email, ip, attempts |
| Account Security Lockout | Account locked out | userId, lockoutEnd |
Email System
The email system supports individual and bulk email sending with template variable interpolation. Emails are queued via background services and processed asynchronously. The system supports scheduling, cancellation, and resending of failed emails.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/emails | List sent/queued/failed emails with pagination and status filters. | 🔒 Required |
| POST | /api/v1/emails/send | Send a single email using a template with variable substitution. | 🔒 Required |
| POST | /api/v1/emails/send-bulk | Send bulk emails to multiple recipients or a filtered group. | 🔒 Required |
| DELETE | /api/v1/emails/{id}/cancel | Cancel a queued (not yet sent) email. | 🔒 Required |
| POST | /api/v1/emails/{id}/resend | Resend a failed email. | 🔒 Required |
| GET | /api/v1/emails/stats | Get email statistics (sent, failed, queued, bounce rate). | 🔒 Required |
| GET | /api/v1/emails/search-recipients | Search for valid email recipients (admins/users) by name or email. | 🔒 Required |
POST /emails/send — RequestJSON
{
"to": "user@example.com",
"subject": "Welcome to SCRIPE",
"templateId": "template-uuid",
"variables": {
"name": "Alice Johnson",
"companyName": "Acme Corp",
"activationUrl": "https://app.scripe.dev/activate?token=..."
},
"priority": "high",
"scheduledAt": null
}Message Templates
Message templates use the Scriban engine (Liquid-compatible) for variable interpolation. Templates support HTML and plain-text bodies, with preview and render endpoints for testing before sending.
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/message-templates | List all message templates with category and status filters. | 🔒 Required |
| GET | /api/v1/message-templates/{id} | Get a single template with full body content and variable definitions. | 🔒 Required |
| POST | /api/v1/message-templates | Create a new message template with HTML/text body and variables. | 🔒 Required |
| PUT | /api/v1/message-templates/{id} | Update a template's content, subject, or variables. | 🔒 Required |
| DELETE | /api/v1/message-templates/{id} | Delete a message template. | 🔒 Required |
| POST | /api/v1/message-templates/{id}/preview | Preview a template with sample data (returns rendered HTML). | 🔒 Required |
| POST | /api/v1/message-templates/{id}/render | Render a template with provided variables (returns final HTML + text). | 🔒 Required |
Message Template ExampleJSON
{
"id": "template-uuid",
"name": "welcome-admin",
"subject": "Welcome to {{companyName}}!",
"bodyHtml": "<h1>Hello {{name}}</h1><p>Welcome to {{companyName}}...</p>",
"bodyText": "Hello {{name}}, Welcome to {{companyName}}...",
"engine": "scriban",
"variables": ["name", "companyName", "activationUrl"],
"category": "onboarding",
"isActive": true
}
// Template engine: Scriban (Liquid-compatible)
// Variables use {{variableName}} syntaxNotifications
| Method | Endpoint | Description | Auth |
|---|---|---|---|
| GET | /api/v1/notifications | List in-app notifications for the current user with pagination. | 🔒 Required |
| GET | /api/v1/notifications/unread-count | Get the count of unread notifications. | 🔒 Required |
| PUT | /api/v1/notifications/{id}/read | Mark a single notification as read. | 🔒 Required |
| PUT | /api/v1/notifications/read-all | Mark all notifications as read. | 🔒 Required |
| DELETE | /api/v1/notifications/{id} | Delete a notification. | 🔒 Required |
| GET | /api/v1/notifications/search-targets | Search for notification targets (users/admins) by name or email. | 🔒 Required |