Webhooks
Receive real-time notifications when events occur in your ContextFile account.
Overview
Webhooks allow you to receive HTTP callbacks when specific events occur. Instead of polling the API for changes, webhooks push data to your server in real-time.
Webhooks require HTTPS
Available Events
Subscribe to the events you want to receive notifications for:
| Event | Description |
|---|---|
context.created | Triggered when a new context file is created |
context.updated | Triggered when a context file is updated |
context.deleted | Triggered when a context file is deleted |
context.published | Triggered when a context file is made public |
context.unpublished | Triggered when a context file is made private |
Webhook Payload
When an event occurs, we send a POST request to your endpoint with a JSON payload:
{
"id": "evt_abc123def456",
"type": "context.updated",
"created_at": "2024-01-15T14:45:00Z",
"data": {
"context": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "My AI Assistant",
"slug": "my-ai-assistant",
"updated_at": "2024-01-15T14:45:00Z"
}
}
}Creating Webhooks
You can create webhooks via the API or through integrations like Zapier.
curl -X POST https://api.contextfile.ai/v1/webhooks \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "My Webhook",
"url": "https://example.com/webhook",
"events": ["context.created", "context.updated"]
}'{
"id": "whk_abc123",
"name": "My Webhook",
"url": "https://example.com/webhook",
"events": ["context.created", "context.updated"],
"secret": "whsec_abc123...",
"is_active": true,
"created_at": "2024-01-15T10:00:00Z"
}Verifying Webhooks
Always verify that webhook requests come from ContextFile by checking the signature.
Always verify signatures
Signature Header
Each webhook request includes a signature in the X-Webhook-Signature header. This is an HMAC-SHA256 hash of the request body using your webhook secret.
import crypto from 'crypto';
function verifyWebhookSignature(payload, signature, secret) {
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
// In your webhook handler
app.post('/webhook', (req, res) => {
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
return res.status(401).send('Invalid signature');
}
// Process the webhook...
res.status(200).send('OK');
});Best Practices
Respond quickly
Return a 2xx response within 5 seconds. Process webhooks asynchronously if needed - add them to a queue and return immediately.
Handle retries
If your endpoint returns an error, we'll retry up to 5 times with exponential backoff. Make sure your handler is idempotent.
Use event IDs for deduplication
Store processed event IDs to prevent handling the same event twice in case of retries or network issues.
Monitor webhook failures
Set up alerts for webhook failures. After multiple failed attempts, we'll disable the webhook and notify you.