Webhooks

The webhooks engine is responsible for 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 endpoint to receive events and are not to be confused with collection and cron outbound 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

From the command line: vski webhooks logs, vski webhooks logs --status failed, vski webhooks trigger <id>.

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

# vski/default/collections.yaml: collection with a test webhook URL
version: 1
database: default

collections:
  test_collection:
    type: base
    fields:
      - {name: data, type: text, required: true}
    options:
      triggers:
        - action: create
          url: https://webhook.site/your-unique-id
          method: POST

# Create a test record to trigger the webhook,
# then check webhook.site to see the payload
await client.collection("test_collection").create({"data": "Test data"})

Manual Testing

await client.collection("notifications").create(
    {"title": "Test Notification", "message": "This is a test", "status": "active"}
)

logs = await client.webhook_logs.list(collection="notifications", page=1, per_page=10)
print(logs)