Webhooks

Webhooks engine is reponsible to executing requests for collection triggers and cron jobs.

• A webhook can send Bearer with JWT payload signed by a VSKI instance.
• Currently webhooks do not support sending files.
• Workflows use a separate inbound enpoint to receive events and not to be confused with collection and cron ourbound webhooks.

API Endpoints

Method	Endpoint	Description
GET	/api/webhooks/logs	List webhook logs
GET	/api/webhooks/logs?collection=name	Filter by collection
GET	/api/webhooks/logs?status=failed	Filter by status
GET	/api/webhooks/logs?page=1&perPage=50	Paginate results

Webhooks are configured via collection management:

Method	Endpoint	Description
POST	/api/collections	Create collection with triggers
PATCH	/api/collections/:name	Update collection triggers

Security Best Practices

1. Use HTTPS - Always use HTTPS URLs for webhooks
2. Secure tokens - Store API tokens in environment variables
3. Verify signatures - Implement signature verification on receiving endpoints (future feature)
4. Rate limiting - Implement rate limiting on webhook endpoints
5. Validate payloads - Always validate incoming webhook data
6. Use authentication - Include authentication headers in triggers
7. Monitor logs - Regularly check webhook logs for failures
8. Test endpoints - Verify webhook endpoints work before production

Testing Webhooks

Using Webhook Testing Services

Use webhook testing services during development:

• https://webhook.site - Get a temporary webhook URL
• https://requestbin.com - Inspect HTTP requests
• ngrok - Expose local endpoints

// Create collection with test webhook URL
await client.settings.collections.create({
  name: "test_collection",
  type: "base",
  schema: [
    { name: "data", type: "text", required: true },
  ],
  options: JSON.stringify({
    triggers: [
      {
        action: "create",
        url: "https://webhook.site/your-unique-id",
        method: "POST",
      },
    ],
  }),
});

// Create test record to trigger webhook
await client.collection("test_collection").create({
  data: "Test data",
});

// Check webhook.site to see the payload

Manual Testing

// Create test record
const testRecord = await client.collection("notifications").create({
  title: "Test Notification",
  message: "This is a test",
  status: "active",
});

// Check logs
const logs = await client.webhookLogs.list({
  collection: "notifications",
  page: 1,
  perPage: 10,
});

console.log(logs);