Webhooks
Receive and process data change events
Webhooks
Receive events on your server when data changes.
Limits
The number of webhooks you can register depends on your plan:
| Plan | Webhooks |
|---|---|
| Free | 1 |
| Starter | 2 |
| Basic | 3 |
| Pro | 4 |
| Enterprise | Unlimited |
Overview
When webhooks are configured, a POST request is sent to the specified URL when the following events occur:
create- New document createdupdate- Document updated
Webhook Setup
Create an API Route
import { handleWebhook } from '@01.software/sdk/webhook'
export async function POST(request: Request) {
return handleWebhook(request, async (event) => {
console.log('Collection:', event.collection)
console.log('Operation:', event.operation)
console.log('Data:', event.data)
})
}Register the Webhook URL
Set the Webhook URL in the tenant settings of the 01.software Console.
https://your-domain.com/api/webhookPayload Structure
WebhookEvent
interface WebhookEvent {
collection: string
operation: 'create' | 'update'
data: any
timestamp: string // ISO 8601
}JSON Example
{
"collection": "posts",
"operation": "create",
"data": {
"id": "post-id",
"title": "Post Title",
"slug": "post-title"
},
"timestamp": "2026-02-24T10:30:45.123Z"
}SDK Handlers
import { handleWebhook, createTypedWebhookHandler } from '@01.software/sdk/webhook'
// Basic handler
export async function POST(request: Request) {
return handleWebhook(request, async (event) => {
if (event.collection === 'posts' && event.operation === 'create') {
revalidatePath('/blog')
}
})
}
// Type-safe handler (event.data is typed as the collection type)
const handlePostWebhook = createTypedWebhookHandler('posts', async (event) => {
revalidatePath('/blog')
revalidatePath(`/blog/${event.data.slug}`)
})
export async function POST(request: Request) {
return handleWebhook(request, handlePostWebhook)
}Security
Signature Verification
The SDK's handleWebhook supports built-in HMAC-SHA256 signature verification via the secret option. Each webhook URL gets its own auto-generated secret (viewable in Console tenant settings). The server signs the payload with that webhook's secret and sends it in the x-webhook-signature header.
export async function POST(request: Request) {
return handleWebhook(request, handler, {
secret: process.env.WEBHOOK_SECRET!,
})
}Error Handling
export async function POST(request: Request) {
return handleWebhook(request, async (event) => {
try {
await processEvent(event)
} catch (error) {
console.error('Webhook processing error:', error)
throw error // Throw error for retry
}
})
}Webhook handlers should process quickly. Offload long-running tasks to background jobs.
Next Steps
- Error Handling - Error handling
- REST API - REST API reference